1 |
Author: zmedico |
2 |
Date: 2009-04-30 06:55:43 +0000 (Thu, 30 Apr 2009) |
3 |
New Revision: 13453 |
4 |
|
5 |
Modified: |
6 |
main/branches/2.1.6/man/egencache.1 |
7 |
Log: |
8 |
- Add more info to the DESCRIPTION section. |
9 |
- Add a BUGS section to explain issues related to limitations in the cache |
10 |
format and its validation mechanism. (trunk r13274) |
11 |
|
12 |
Modified: main/branches/2.1.6/man/egencache.1 |
13 |
=================================================================== |
14 |
--- main/branches/2.1.6/man/egencache.1 2009-04-30 06:55:20 UTC (rev 13452) |
15 |
+++ main/branches/2.1.6/man/egencache.1 2009-04-30 06:55:43 UTC (rev 13453) |
16 |
@@ -5,7 +5,9 @@ |
17 |
.B egencache |
18 |
.I [options] --update [ATOM]\fR... |
19 |
.SH "DESCRIPTION" |
20 |
-The egencache program generates metadata cache for ebuild repositories. |
21 |
+The egencache program generates metadata cache for ebuild repositories and |
22 |
+stores it in the \fImetadata/cache/\fR directory within the repository itself, |
23 |
+for distribution. |
24 |
.SH ACTIONS |
25 |
.TP |
26 |
.BR "\-\-update [ATOM] ... " |
27 |
@@ -15,7 +17,9 @@ |
28 |
.SH OPTIONS |
29 |
.TP |
30 |
.BR "\-\-cache\-dir=CACHE_DIR" |
31 |
-Location of the metadata cache. |
32 |
+Location of the intermediate metadata cache which is stored in a different |
33 |
+format that includes eclass state. See the \fBBUGS\fR section for |
34 |
+information about why this is necessary. |
35 |
.br |
36 |
Defaults to /var/cache/edb/dep. |
37 |
.TP |
38 |
@@ -51,6 +55,31 @@ |
39 |
contains will be added to the beginning of the command line on every |
40 |
invocation. These options will not be added if the |
41 |
\fB\-\-ignore-default\-opts\fR option is specified. |
42 |
+.SH "BUGS" |
43 |
+There are significant limitations associated with the metadata |
44 |
+cache format that is distributed in the \fImetadata/cache/\fR directory |
45 |
+of the repository. These limitations are related to the cache validation |
46 |
+mechanism. Currently, the validation mechanism involves comparison of |
47 |
+a cache entry mtime to the mtime of the corresponding \fBebuild(5)\fR. This |
48 |
+mechanism is unreliable in cases when eclass changes result in metadata |
49 |
+changes, since no information about eclass state is available in the cache. |
50 |
+Also, since the mtime of the cache entry must correspond to that of the |
51 |
+ebuild, the cache format is only suitable for distribution via protocols |
52 |
+that preserve timestamps (such as \fBrsync(1))\fR. For cache that is |
53 |
+distributed via \fBgit(1)\fR repositories, there is currently a workaround |
54 |
+implemented in \fBemerge\fR(1) \fB\-\-sync\fR which updates ebuild mtimes |
55 |
+to match their corresponding cache entries (except for ebuilds that are |
56 |
+modified relative to HEAD). |
57 |
+ |
58 |
+In order to solve the above problems, a future extension |
59 |
+to the cache format will include additional |
60 |
+validation data in the form of digests for both the ebuild |
61 |
+and its inherited eclasses. Until the |
62 |
+cache format has been extended in this way, it is necessary to enable |
63 |
+\fBmetadata-transfer\fR in \fBFEATURES\fR (see \fBmake.conf(5)\fR). |
64 |
+This causes intermediate cache (in a different format that includes |
65 |
+eclass state) to be generated inside the directory which is configurable |
66 |
+via the \fB\-\-cache\-dir\fR option. |
67 |
.SH "REPORTING BUGS" |
68 |
Please report bugs via http://bugs.gentoo.org/ |
69 |
.SH "AUTHORS" |