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