summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorZac Medico <zmedico@gentoo.org>2009-04-01 19:13:14 +0000
committerZac Medico <zmedico@gentoo.org>2009-04-01 19:13:14 +0000
commit9529d89b4ea1e29207a175bc1fc7b4945f032285 (patch)
treea306575afa72d66948617e9cc2a280e8a44e2014
parenta70afbccafa38a013da34033fdca7d8561e2741a (diff)
downloadportage-9529d89b4ea1e29207a175bc1fc7b4945f032285.tar.gz
portage-9529d89b4ea1e29207a175bc1fc7b4945f032285.tar.bz2
portage-9529d89b4ea1e29207a175bc1fc7b4945f032285.zip
- Add more info to the DESCRIPTION section.
- Add a BUGS section to explain issues related to limitations in the cache format and its validation mechanism. svn path=/main/trunk/; revision=13274
-rw-r--r--man/egencache.133
1 files changed, 31 insertions, 2 deletions
diff --git a/man/egencache.1 b/man/egencache.1
index c641f036b..4891a34af 100644
--- a/man/egencache.1
+++ b/man/egencache.1
@@ -5,7 +5,9 @@ egencache \- generate metadata cache for ebuild repositories
.B egencache
.I [options] --update [ATOM]\fR...
.SH "DESCRIPTION"
-The egencache program generates metadata cache for ebuild repositories.
+The egencache program generates metadata cache for ebuild repositories and
+stores it in the \fImetadata/cache/\fR directory within the repository itself,
+for distribution.
.SH ACTIONS
.TP
.BR "\-\-update [ATOM] ... "
@@ -15,7 +17,9 @@ for the details on package atom syntax.
.SH OPTIONS
.TP
.BR "\-\-cache\-dir=CACHE_DIR"
-Location of the metadata cache.
+Location of the intermediate metadata cache which is stored in a different
+format that includes eclass state. See the \fBBUGS\fR section for
+information about why this is necessary.
.br
Defaults to /var/cache/edb/dep.
.TP
@@ -51,6 +55,31 @@ If this variable is set in \fBmake.conf\fR(5) then any options that it
contains will be added to the beginning of the command line on every
invocation. These options will not be added if the
\fB\-\-ignore-default\-opts\fR option is specified.
+.SH "BUGS"
+There are significant limitations associated with the metadata
+cache format that is distributed in the \fImetadata/cache/\fR directory
+of the repository. These limitations are related to the cache validation
+mechanism. Currently, the validation mechanism involves comparison of
+a cache entry mtime to the mtime of the corresponding \fBebuild(5)\fR. This
+mechanism is unreliable in cases when eclass changes result in metadata
+changes, since no information about eclass state is available in the cache.
+Also, since the mtime of the cache entry must correspond to that of the
+ebuild, the cache format is only suitable for distribution via protocols
+that preserve timestamps (such as \fBrsync(1))\fR. For cache that is
+distributed via \fBgit(1)\fR repositories, there is currently a workaround
+implemented in \fBemerge\fR(1) \fB\-\-sync\fR which updates ebuild mtimes
+to match their corresponding cache entries (except for ebuilds that are
+modified relative to HEAD).
+
+In order to solve the above problems, a future extension
+to the cache format will include additional
+validation data in the form of digests for both the ebuild
+and its inherited eclasses. Until the
+cache format has been extended in this way, it is necessary to enable
+\fBmetadata-transfer\fR in \fBFEATURES\fR (see \fBmake.conf(5)\fR).
+This causes intermediate cache (in a different format that includes
+eclass state) to be generated inside the directory which is configurable
+via the \fB\-\-cache\-dir\fR option.
.SH "REPORTING BUGS"
Please report bugs via http://bugs.gentoo.org/
.SH "AUTHORS"