-.TH "EMERGE" "1" "Sep 2012" "Portage VERSION" "Portage"
+.TH "EMERGE" "1" "Jul 2013" "Portage VERSION" "Portage"
.SH "NAME"
emerge \- Command\-line interface to the Portage system
.SH "SYNOPSIS"
\fB\-\-search\fR \fIsomestring\fR
.TP
.BR emerge
-\fB\-\-help\fR [\fB\-\-verbose\fR]
+\fB\-\-help\fR
.SH "DESCRIPTION"
\fBemerge\fR is the definitive command\-line interface to the Portage
system. It is primarily used for installing packages, and \fBemerge\fR
Displays a list of available package sets.
.TP
.BR \-\-metadata
-Transfers metadata cache from ${PORTDIR}/metadata/cache/ to
+Transfers metadata cache from ${PORTDIR}/metadata/md5\-cache/ to
/var/cache/edb/dep/ as is normally done on the
tail end of an rsync update using \fBemerge \-\-sync\fR. This process
populates the cache database that portage uses for pre-parsed lookups of
.TP
.BR "\-\-resume" (\fB\-r\fR)
Resumes the most recent merge list that has been aborted due to an error.
-This re\-uses the options that were given with the original
+This re\-uses the arguments and options that were given with the original
command that's being resumed, and the user may also provide
-additional options when calling \fB\-\-resume\fR.
+additional options when calling \fB\-\-resume\fR. It is an error to provide
+atoms or sets as arguments to \fB\-\-resume\fR, since the arguments from the
+resumed command are used instead.
Please note that this operation will only return an error on failure. If there
is nothing for portage to do, then portage will exit with a message and a
success condition. A resume list will persist until it has been completed in
entirety or until another aborted merge list replaces it. The resume history
is capable of storing two merge lists. After one resume list completes, it is
possible to invoke \-\-resume once again in order to resume an older list.
+The resume lists are stored in \fI/var/cache/edb/mtimedb\fR, and may be
+explicitly discarded by running `emaint \-\-fix cleanresume` (see
+\fBemaint\fR(1)).
.TP
.BR "\-\-search " (\fB\-s\fR)
Searches for matches of the supplied string in the portage tree.
matched as regular expressions.
.TP
.BR \-\-sync
-This updates the portage tree that is located in the
-directory that the PORTDIR variable refers to (default
-location is /usr/portage). The SYNC variable specifies
-the remote URI from which files will be synchronized.
+Updates repositories, for which sync\-type and sync\-uri attributes are
+set in repos.conf. See \fBportage\fR(5) for more information.
The \fBPORTAGE_SYNC_STALE\fR variable configures
warnings that are shown when emerge \-\-sync has not
been executed recently.
\fBWARNING:\fR
-The emerge \-\-sync action will modify and/or delete
-files located inside the directory that the PORTDIR
-variable refers to (default location is /usr/portage).
-For more information, see the PORTDIR documentation in
-the make.conf(5) man page.
+The emerge \-\-sync action will revert local changes (e.g. modifications or
+additions of files) inside repositories synchronized using rsync.
\fBNOTE:\fR
The \fBemerge\-webrsync\fR program will download the entire
configuration, this would result in an effective
\fBACCEPT_PROPERTIES\fR value of "* -interactive".
.TP
+.BR \-\-accept\-restrict=ACCEPT_RESTRICT
+This option temporarily overrides the \fBACCEPT_RESTRICT\fR
+variable. The \fBACCEPT_RESTRICT\fR variable is incremental,
+which means that the specified setting is appended to the
+existing value from your configuration. The special \fB-*\fR
+token can be used to discard the existing configuration
+value and start fresh. See the \fBMASKED PACKAGES\fR section
+and \fBmake.conf\fR(5) for more information about
+ACCEPT_RESTRICT. A typical usage example for this option
+would be to use \fI\-\-accept\-restrict=\-bindist\fR to
+temporarily mask packages that are not binary
+re\-distributable. With default
+configuration, this would result in an effective
+\fBACCEPT_RESTRICT\fR value of "* -bindist".
+.TP
.BR "\-\-alphabetical "
When displaying USE and other flag output, combines the enabled and
disabled lists into one list and sorts the whole list alphabetically.
.TP
.BR "\-\-depclean\-lib\-check [ y | n ]"
Account for library link-level dependencies during
-\fB\-\-depclean\fR and \fB\-\-prune\fR actions. This
-option is enabled by default. In some cases this can
-be somewhat time\-consuming. This option is ignored
-when FEATURES="preserve\-libs" is enabled in
-\fBmake.conf\fR(5), since any libraries that have
-consumers will simply be preserved.
+\fB\-\-depclean\fR and \fB\-\-prune\fR actions.
+This option is enabled by default. If FEATURES="preserve\-libs" is
+enabled in \fBmake.conf\fR(5), and preserve\-libs is not restricted
+for any of the packages selected for removal, then this option is
+ignored because any libraries that have consumers will simply be
+preserved.
+.TP
+.BR \-\-digest
+Prevent corruption from being noticed. The `repoman manifest` command is the
+preferred way to generate manifests and it is capable of doing an entire
+repository or category at once (see \fBrepoman\fR(1)).
.TP
.BR "\-\-dynamic\-deps < y | n >"
In dependency calculations, substitute the dependencies of installed
unsatisfied dependencies are automatically dropped. Also see
the related \fB\-\-skipfirst\fR option.
.TP
-.BR \-\-load\-average=LOAD
+.BR "\-\-load\-average [LOAD]"
Specifies that no new builds should be started if there are other builds
running and the load average is at least LOAD (a floating-point number).
+With no argument, removes a previous load limit.
This option is recommended for use in combination with \fB\-\-jobs\fR in
order to avoid excess load. See \fBmake\fR(1) for information about
analogous options that should be configured via \fBMAKEOPTS\fR in
regardless of whether or not any of the package moves have
been previously applied.
.TP
+.BR \-\-pkg\-format
+Specify which binary package format will be created as target.
+Possible choices now are tar and rpm or their combinations.
+.TP
+.BR \-\-prefix=DIR
+Set the \fBEPREFIX\fR environment variable.
+.TP
.BR "\-\-pretend " (\fB\-p\fR)
Instead of actually performing the merge, simply display what *would*
have been installed if \fB\-\-pretend\fR weren't used. Using \fB\-\-pretend\fR
S new SLOT installation (side-by-side versions)
U updating (to another version)
D downgrading (best version seems lower)
-r reinstall (forced due to slot or sub\-slot change of a dependency)
+r reinstall (forced for some reason, possibly due to slot or sub\-slot)
R replacing (remerging same version)
F fetch restricted (must be manually downloaded)
f fetch restricted (already downloaded)
.BR "\-\-quiet\-build [ y | n ]"
Redirect all build output to logs alone, and do not display it on
stdout. If a build failure occurs for a single package, the build
-log will be automatically displayed on stdout. If there are multiple
+log will be automatically displayed on stdout (unless the
+\fI\-\-quiet\-fail\fR option is enabled). If there are multiple
build failures (due to options like \-\-keep\-going or \-\-jobs),
then the content of the log files will not be displayed, and instead
the paths of the log files will be displayed together with the
be displayed on stdout. This issue can be temporarily avoided
by specifying \fI\-\-accept\-properties=\-interactive\fR.
.TP
+.BR "\-\-quiet\-fail [ y | n ]"
+Suppresses display of the build log on stdout when build output is hidden
+due to options such as \fI\-\-jobs\fR, \fI\-\-quiet\fR, or
+\fI\-\-quiet\-build\fR. Only the die message and the path of the build log
+will be displayed on stdout.
+.TP
.BR "\-\-quiet\-repo\-display"
In the package merge list display, suppress ::repository output, and
instead use numbers to indicate which repositories package come from.
checking of reverse dependencies, it enables \-\-complete\-graph
mode whenever a new slot is installed. This option is enabled by
default.
+
+NOTE: If you want to skip all rebuilds involving slot\-operator
+dependecies (including those that involve sub\-slot changes alone),
+then \fI\-\-ignore\-built\-slot\-operator\-deps=y\fR is the option
+that you are looking for, since \fI\-\-rebuild\-if\-new\-slot\fR
+does not affect rebuilds triggered by sub\-slot changes alone.
.TP
.BR "\-\-rebuild\-if\-new\-rev [ y | n ]"
Rebuild packages when build\-time dependencies are built from source, if the
.TP
.BR "\-\-root\-deps[=rdeps]"
If no argument is given then build\-time dependencies of packages for
-\fBROOT\fR are installed to
-\fBROOT\fR instead of /. If the \fBrdeps\fR argument is given then discard
-all build\-time dependencies of packages for \fBROOT\fR. This option is
-only meaningful when used together with \fBROOT\fR and it should not
-be enabled under normal circumstances. For currently supported
-\fBEAPI\fR values, the build-time dependencies are specified in the
-\fBDEPEND\fR variable. However, behavior may change for new
-\fBEAPI\fRs when related extensions are added in the future.
-.TP
-.BR "\-\-select [ y | n ]"
+\fBROOT\fR are installed to \fBROOT\fR instead of /.
+If the \fBrdeps\fR argument is given then discard all build\-time dependencies
+of packages for \fBROOT\fR.
+This option is only meaningful when used together with \fBROOT\fR and it should
+not be enabled under normal circumstances!
+
+Does not affect EAPIs that support \fBHDEPEND\fR.
+Experimental \fBEAPI 5-hdepend\fR provides \fBHDEPEND\fR as a new
+means to adjust installation into "\fI/\fR" and \fBROOT\fR.
+If ebuilds using EAPIs which \fIdo not\fR support \fBHDEPEND\fR are built in
+the same \fBemerge\fR run as those using EAPIs which \fIdo\fR support
+\fBHDEPEND\fR, this option affects only the former.
+.TP
+.BR "\-\-select [ y | n ] (\-w short option)"
Add specified packages to the world set (inverse of
\fB\-\-oneshot\fR). This is useful if you want to
use \fBEMERGE_DEFAULT_OPTS\fR to make
will simply abort. Portage does not use $PORTDIR when calculating dependency
information so all masking information is ignored.
.TP
-.BR "\-\-verbose " (\fB\-v\fR)
+.BR "\-\-verbose [ y | n ] (\-v short option)"
Tell emerge to run in verbose mode. Currently this flag causes emerge to print
out GNU info errors, if any, and to show the USE flags that will be used for
each package when pretending. The following symbols are affixed to USE flags
command line.
.SH "ENVIRONMENT OPTIONS"
.TP
+\fBEPREFIX\fR = \fI[path]\fR
+Use \fBEPREFIX\fR to specify the target prefix to be used for merging packages
+or ebuilds. This variable can be set via the \fB\-\-prefix\fR
+option or in \fBmake.conf\fR(5) (the command line overrides other settings).
+.br
+Defaults to the prefix where portage is currently installed.
+.TP
\fBROOT\fR = \fI[path]\fR
Use \fBROOT\fR to specify the target root filesystem to be used for
merging packages or ebuilds. This variable can be set via the \fB\-\-root\fR
Using the \fB\-\-quiet\fR option will prevent all information from being
displayed.
.TP
+.B [ebuild r U ] dev\-libs/icu\-50.1.1:0/50.1.1 [50.1\-r2:0/50.1]
+Icu 50.1\-r2 has already been emerged and can be Updated to version
+50.1.1. The \fBr\fR symbol indicates that a sub\-slot change (from 50.1
+to 50.1.1 in this case) will force packages having slot\-operator
+dependencies on it to be rebuilt (as libxml2 will be rebuilt in the next
+example).
+.TP
+.B [ebuild rR ] dev\-libs/libxml2\-2.9.0\-r1:2 USE="icu"
+Libxml2 2.9.0\-r1 has already been emerged, but if you run the command,
+then portage will Re\-emerge it in order to satisfy a slot\-operator
+dependency which forces it to be rebuilt when the icu sub\-slot changes
+(as it changed in the previous example).
+.TP
.B [ebuild U *] sys\-apps/portage\-2.2.0_alpha6 [2.1.9.25]
Portage 2.1.9.25 is installed, but if you run the command, then
portage will upgrade to version 2.2.0_alpha6. In this case,
about \fBACCEPT_PROPERTIES\fR, and see \fBportage\fR(5) for information about
\fI/etc/portage/package.properties\fR. Use the \fB\-\-accept\-properties\fR
option to temporarily override \fBACCEPT_PROPERTIES\fR.
+.TP
+.BR RESTRICT
+The \fBRESTRICT\fR variable in an \fBebuild\fR file can be used to mask
+packages based on RESTRICT tokens. \fBemerge\fR examines the
+\fBACCEPT_RESTRICT\fR environment variable to allow or disallow the emerging
+of a package masked by \fBRESTRICT\fR. See \fBmake.conf\fR(5) for information
+about \fBACCEPT_RESTRICT\fR, and see \fBportage\fR(5) for information about
+\fI/etc/portage/package.accept_restrict\fR. Use the \fB\-\-accept\-restrict\fR
+option to temporarily override \fBACCEPT_RESTRICT\fR.
.SH "CONFIGURATION FILES"
Portage has a special feature called "config file protection". The purpose of
this feature is to prevent new package installs from clobbering existing
directories can be specified using the \fICONFIG_PROTECT_MASK\fR variable. To find
files that need to be updated in /etc, type \fBfind /etc \-iname \'._cfg????_*\'\fR.
.LP
-You can disable this feature by setting \fICONFIG_PROTECT="\-*"\fR in /etc/make.conf.
+You can disable this feature by setting \fICONFIG_PROTECT="\-*"\fR in \fBmake.conf\fR(5).
Then, Portage will mercilessly auto\-update your config files. Alternatively,
you can leave Config File Protection on but tell Portage that it can overwrite
files in certain specific /etc subdirectories. For example, if you wanted
Portage to automatically update your rc scripts and your wget configuration,
but didn't want any other changes made without your explicit approval, you'd
-add this to /etc/make.conf:
+add this to \fBmake.conf\fR(5):
.LP
.I CONFIG_PROTECT_MASK="/etc/wget /etc/rc.d"
.LP
Jason Stubbs <jstubbs@gentoo.org>
Brian Harring <ferringb@gmail.com>
Zac Medico <zmedico@gentoo.org>
+Arfrever Frehtes Taifersar Arahesis <arfrever@apache.org>
.fi
.SH "FILES"
Here is a common list of files you will probably be interested in. For a
packages sets which always begin with the \fB@\fR character. Use
\fB/etc/portage/sets/\fR to define user package sets.
.TP
-.B /etc/make.conf
+.B /etc/portage/make.conf
Contains variables for the build process, overriding those in
\fBmake.globals\fR.
.TP
projects / portage.git / blobdiff