.TH "EGENCACHE" "1" "March 2009" "Portage VERSION" "Portage"
.SH "NAME"
egencache \- generate metadata cache for ebuild repositories
.SH "SYNOPSIS"
.B egencache
.I [options] --update [ATOM]\fR...
.SH "DESCRIPTION"
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] ... "
Update the \fImetadata/cache/\fR directory (generate metadata as necessary).
If no package atoms are specified then all will be updated. See ebuild(5)
for the details on package atom syntax.
.TP
.BR "\-\-update\-use\-local\-desc"
Update the \fIprofiles/use.local.desc\fR file from metadata.xml.
.SH OPTIONS
.TP
.BR "\-\-cache\-dir=CACHE_DIR"
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
.BR "\-\-config\-root=PORTAGE_CONFIGROOT"
Location of portage config files.
.br
Defaults to /.
.TP
.BR "\-\-ignore-default-opts"
Causes \fIEGENCACHE_DEFAULT_OPTS\fR to be ignored.
.TP
.BR "\-\-jobs=JOBS"
Specifies the maximum number of ebuild processes to spawn simultaneously.
Also see the related \fB\-\-load\-average\fR option.
.TP
.BR \-\-load\-average=LOAD
Specifies that maximum load allowed when spawning multiple jobs.
.TP
.BR "\-\-portdir=PORTDIR"
Override the portage tree location.
.TP
.BR "\-\-preserve\-comments"
Preserve the comments found in the output use.local.desc file. This requires
the output file to exist before egencache is called.
.TP
.BR "\-\-repo=REPO"
Name of the repo to operate on (default repo is located at \fBPORTDIR\fR).
The name should correspond the value of a \fBrepo_name\fR entry (see
\fBportage\fR(5)) from one of the repositories that is configured via the
\fBPORTDIR\fR or \fBPORTDIR_OVERLAY\fR variables (see \fBmake.conf\fR(5)).
.TP
.BR "\-\-rsync"
When used together with the \fB\-\-update\fR action, this enables a workaround
for cases in which the content of a cache entry changes and neither the file
mtime nor size changes, preventing rsync from detecting changes. Such cases are
handled by bumping the mtime on the ebuild (and the corresponding cache entry).
This option should only be needed for distribution via something like
\fBrsync\fR(1), which relies on timestamps and file sizes to detect changes
(see \fBbug 139134\fR). It's not needed with \fBgit\fR(1) since that uses a
more thorough mechanism which allows it to detect changed inode numbers
(described in \fIracy-git.txt\fR in the git technical docs).
.TP
.BR "\-\-tolerant"
Exit successfully if only minor errors occurred, such as skipped cache
updates due to ebuilds that either fail to source or are not sourced
due to invalid Manifest entries.
.TP
.BR "\-\-use\-local\-desc\-output=ULD_OUTPUT"
output file for use.local.desc data (or '-' for stdout)
.SH "ENVIRONMENT OPTIONS"
.TP
\fBEGENCACHE_DEFAULT_OPTS\fR
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"
.nf
Zac Medico <zmedico@gentoo.org>
.fi
.SH "FILES"
.TP
.B /etc/make.conf
Contains variables.
.SH "SEE ALSO"
.BR emerge (1),
.BR make.conf (5),
.BR portage (5)