| .TH "EGENCACHE" "1" "March 2009" "Portage 2.2" "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. |
| .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=CONFIG_ROOT" |
| 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 "\-\-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). |
| .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) |