| .TH "EGENCACHE" "1" "Jul 2013" "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/md5\-cache/\fR directory within the repository |
| itself, for distribution. |
| .SH ACTIONS |
| .TP |
| .BR "\-\-update [ATOM] ... " |
| Update the \fImetadata/md5\-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\-changelogs" |
| Update the ChangeLog files from SCM logs (supported only in git repos). |
| .TP |
| .BR "\-\-update\-use\-local\-desc" |
| Update the \fIprofiles/use.local.desc\fR file from metadata.xml. |
| .TP |
| .BR "\-\-update\-manifests" |
| Update manifest files, and sign them if signing is enabled. This supports |
| parallelization if enabled via the \-\-jobs option. The \-\-thin\-manifests |
| and \-\-sign\-manifests options may be used to manually override layout.conf |
| settings. |
| .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 "\-\-gpg\-dir" |
| Override the PORTAGE_GPG_DIR variable. |
| .TP |
| .BR "\-\-gpg\-key" |
| Override the PORTAGE_GPG_KEY variable. |
| .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 PORTDIR variable. This option is deprecated in favor of |
| \-\-repositories\-configuration option. |
| .TP |
| .BR "\-\-portdir\-overlay=PORTDIR_OVERLAY" |
| Override the PORTDIR_OVERLAY variable. This option is deprecated in favor of |
| \-\-repositories\-configuration option. |
| .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. The name should correspond the value of |
| a \fBrepo_name\fR entry (see \fBportage\fR(5)) from one of the repositories. |
| .TP |
| .BR "\-\-repositories\-configuration=REPOSITORIES_CONFIGURATION" |
| Override configuration of repositories. The argument of this option has |
| the same format as repos.conf (see \fBportage\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 "\-\-sign\-manifests< y | n >" |
| Manually override layout.conf sign-manifests setting. |
| .TP |
| .BR "\-\-strict\-manifests< y | n >" |
| Manually override "strict" FEATURES setting. |
| .TP |
| .BR "\-\-thin\-manifests< y | n >" |
| Manually override layout.conf thin-manifests setting. |
| .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" |
| Prior to portage-2.1.11.32, the 'pms' cache format was enabled by default. |
| This 'pms' format, which is distributed in the \fImetadata/cache/\fR |
| directory of the repository, has significant limitations related to the |
| cache validation mechanism which 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, the newer 'md5-dict' format has been |
| enabled by default since portage-2.1.11.32. This format is distributed in |
| the \fImetadata/md5-cache/\fR directory of the repository, and includes |
| additional validation data in the form of digests for both the ebuild |
| and its inherited eclasses. \fBWARNING:\fR Portage versions prior to |
| portage-2.1.11.14 will \fBNOT\fR recognize the 'md5-dict' format unless it is |
| explicitly listed in \fImetadata/layout.conf\fR (refer to \fBportage\fR(5) |
| for example usage). |
| |
| \fBWARNING:\fR For backward compatibility, the obsolete 'pms' cache format |
| will still be generated by default if the \fImetadata/cache/\fR directory |
| exists in the repository. It can also be explicitly enabled via the |
| cache\-formats setting in \fImetadata/layout.conf\fR (refer to \fBportage\fR(5) |
| for example usage). If the 'pms' cache format is enabled and the 'md5-dict' |
| format is not enabled, then 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> |
| Arfrever Frehtes Taifersar Arahesis <arfrever@apache.org> |
| .fi |
| .SH "FILES" |
| .TP |
| .B /etc/portage/make.conf |
| Contains variables. |
| .SH "SEE ALSO" |
| .BR emerge (1), |
| .BR make.conf (5), |
| .BR portage (5) |
