.TP
.BR set
A \fIset\fR is a convenient shorthand for a large group of
-packages. Two sets are currently always available: \fBsystem\fR
-and \fBworld\fR. \fBsystem\fR refers to a set of packages
-deemed necessary for your system to run properly. \fBworld\fR
-contains all the packages listed in \fB/var/lib/portage/world\fR. [See
+packages. Three sets are currently always available: \fBselected\fR,
+\fBsystem\fR and \fBworld\fR. \fBselected\fR contains the user-selected
+"world" packages that are listed in \fB/var/lib/portage/world\fR,
+and nested sets that may be listed
+in \fB/var/lib/portage/world_sets\fR. \fBsystem\fR refers to a set of
+packages deemed necessary for your system to run properly. \fBworld\fR
+encompasses both the \fBselected\fR and \fBsystem\fR sets. [See
\fBFILES\fR below for more information.] Other sets can exist depending
on the current configuration. The default set configuration is located
in \fB/usr/share/portage/config/sets.conf\fR. Note that a \fIset\fR
to the \fBworld\fR file at the end, so that they are considered for
later updating.
.TP
-.BR "\-\-clean " (\fB\-c\fR)
+.BR \-\-clean
Cleans up the system by examining the installed packages and removing older
packages. This is accomplished by looking at each installed package and separating
the installed versions by \fBslot\fR. Clean will \fBremove all but the most recently
has completed. This usually entails configuration file setup or other similar
setups that the user may wish to run.
.TP
-.BR \-\-depclean
+.BR "\-\-depclean (-c)"
Cleans the system by removing packages that are not associated
with explicitly merged packages. Depclean works by creating the
-full dependency tree from the @system and @world sets,
+full dependency tree from the @world set,
then comparing it to installed packages. Packages installed, but
not part of the dependency tree, will be uninstalled by depclean.
See \fB\-\-with\-bdeps\fR for behavior with respect to build time dependencies
\-\-noreplace <atom>\fR. As a safety measure, depclean will not remove any
packages unless *all* required dependencies have been resolved. As a
consequence, it is often necessary to run \fIemerge \-\-update \-\-newuse
-\-\-deep @system @world\fR prior to depclean.
+\-\-deep @world\fR prior to depclean.
\fBWARNING:\fR
Inexperienced users are advised to use \fB\-\-pretend\fR with this
the \fB\-\-jobs\fR and \fB\-\-load\-average\fR options. If you would like to
generate and distribute cache for use by others, use \fBegencache\fR(1).
.TP
-.BR "\-\-resume"
+.BR "\-\-resume" (\fB\-r\fR)
Resumes the most recent merge list that has been aborted due to an error.
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
.TP
.BR "\-\-update " (\fB\-u\fR)
Updates packages to the best version available, which may not always be the
-highest version number due to masking for testing and development. This will
-also update direct dependencies which may not be what you want. Package atoms
+highest version number due to masking for testing and development.
+Package atoms
specified on the command line are greedy, meaning that unspecific atoms may
match multiple installed versions of slotted packages.
.TP
Displays the version number of \fBemerge\fR.
.SH "OPTIONS"
.TP
+.BR \-\-accept\-properties=ACCEPT_PROPERTIES
+This option temporarily overrides the \fBACCEPT_PROPERTIES\fR
+variable. The \fBACCEPT_PROPERTIES\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_PROPERTIES. A typical usage example for this option
+would be to use \fI\-\-accept\-properties=\-interactive\fR to
+temporarily mask interactive packages. With default
+configuration, this would result in an effective
+\fBACCEPT_PROPERTIES\fR value of "* -interactive".
+.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.
\fBWARNING: If the "Enter" key is pressed at the prompt (with no other input),
it is interpreted as acceptance of the first choice. Note that the input
buffer is not cleared prior to the prompt, so an accidental press of the
-"Enter" key at any time prior to the prompt will be interpreted as a choice!\fR
+"Enter" key at any time prior to the prompt will be interpreted as a choice!
+Use the \-\-ask\-enter\-invalid option if you want a single "Enter" key
+press to be interpreted as invalid input.\fR
+.TP
+.BR "\-\-ask\-enter\-invalid"
+When used together with the \fB\-\-ask\fR option,
+interpret a single "Enter" key press as
+invalid input. This helps prevent accidental
+acceptance of the first choice. This option is
+intended to be set in the \fBmake.conf\fR(5)
+\fBEMERGE_DEFAULT_OPTS\fR variable.
+.TP
+.BR \-\-backtrack=COUNT
+Specifies an integer number of times to backtrack if
+dependency calculation fails due to a conflict or an
+unsatisfied dependency (default: \'5\').
.TP
.BR "\-\-binpkg\-respect\-use < y | n >"
Tells emerge to ignore binary packages if their use flags
merging the packages. This comes with the caveat that all build-time
dependencies must already be emerged on the system.
.TP
+.BR "\-\-changed\-use"
+This is an alias for \fB\-\-reinstall=changed\-use\fR.
+.TP
.BR "\-\-changelog " (\fB\-l\fR)
Use this in conjunction with the \fB\-\-pretend\fR option. This will
show the ChangeLog entries for all the packages that will be upgraded.
Used alongside \fB\-\-pretend\fR to cause the package name, new version,
and old version to be displayed in an aligned format for easy cut\-n\-paste.
.TP
-.BR "\-\-complete\-graph"
+.BR "\-\-complete\-graph[=n]"
This causes \fBemerge\fR to consider the deep dependencies of all
-packages from the system and world sets. With this option enabled,
+packages from the world set. With this option enabled,
\fBemerge\fR will bail out if it determines that the given operation will
break any dependencies of the packages that have been added to the
graph. Like the \fB\-\-deep\fR option, the \fB\-\-complete\-graph\fR
it to output verbose debugging information to stdout. This also enables
a plethora of other output (mostly dependency resolution messages).
.TP
-.BR "\-\-deep " (\fB\-D\fR)
+.BR "\-\-deep [DEPTH] " (\fB\-D\fR)
This flag forces
\fBemerge\fR to consider the entire dependency tree of packages,
instead of checking only the immediate dependencies of the packages.
little as possible. You should run with \fB\-\-pretend\fR first to make
sure the result is what you expect.
.TP
+.BR "\-\-fail\-clean[=n]"
+Clean up temporary files after a build failure. This is
+particularly useful if you have \fBPORTAGE_TMPDIR\fR on
+tmpfs. If this option is enabled, you probably also want
+to enable \fBPORT_LOGDIR\fR (see \fBmake.conf\fR(5)) in
+order to save the build log.
+.TP
.BR "\-\-fetchonly " (\fB\-f\fR)
Instead of doing any package building, just perform fetches for all
packages (fetch things from SRC_URI based upon USE setting).
Instead of doing any package building, just perform fetches for all
packages (fetch everything in SRC_URI regardless of USE setting).
.TP
-.BR "\-\-getbinpkg " (\fB\-g\fR)
+.BR "\-\-getbinpkg[=n] " (\fB\-g\fR)
Using the server and location defined in \fIPORTAGE_BINHOST\fR (see
\fBmake.conf\fR(5)), portage will download the information from each binary
package found and it will use that information to help build the dependency
list. This option implies \fB\-k\fR. (Use \fB\-gK\fR for binary\-only
merging.)
.TP
-.BR "\-\-getbinpkgonly " (\fB\-G\fR)
+.BR "\-\-getbinpkgonly[=n] " (\fB\-G\fR)
This option is identical to \fB\-g\fR, as above, except binaries from the
remote server are preferred over local packages if they are not identical.
.TP
Specifies the number of packages to build simultaneously. If this option is
given without an argument, emerge will not limit the number of jobs that can
run simultaneously. Also see the related \fB\-\-load\-average\fR option.
+Note that interactive packages currently force a setting
+of \fI\-\-jobs=1\fR. This issue can be temporarily avoided
+by specifying \fI\-\-accept\-properties=\-interactive\fR.
.TP
-.BR "\-\-keep\-going"
+.BR "\-\-keep\-going[=n]"
Continue as much as possible after an error. When an error occurs,
dependencies are recalculated for remaining packages and any with
unsatisfied dependencies are automatically dropped. Also see
\fBmake.conf\fR(5).
.TP
.BR "\-\-newuse " (\fB\-N\fR)
-Tells emerge to include installed packages where USE flags have changed since
-compilation. USE flag changes include:
+Tells emerge to include installed packages where USE
+flags have changed since compilation. This option
+also implies the \fB\-\-selective\fR option.
+USE flag changes include:
A USE flag was added to a package.
A USE flag was removed from a package.
Results may vary, but the general outcome is a reduced or condensed
output from portage's displays.
.TP
+.BR \-\-quiet\-build
+Redirect all build output to logs alone, and do not
+display it on stdout.
+.TP
+.BR "\-\-rebuilt\-binaries[=n]"
+Replace installed packages with binary packages that have
+been rebuilt. Rebuilds are detected by comparison of
+BUILD_TIME package metadata. This option is enabled
+automatically when using binary packages
+(\fB\-\-usepkgonly\fR or \fB\-\-getbinpkgonly\fR) together with
+\fB\-\-update\fR and \fB\-\-deep\fR.
+.TP
.BR "\-\-reinstall changed\-use"
Tells emerge to include installed packages where USE flags have
changed since installation. Unlike \fB\-\-newuse\fR, this option does
\fBDEPEND\fR variable. However, behavior may change for new
\fBEAPI\fRs when related extensions are added in the future.
.TP
-.BR "\-\-selective"
+.BR "\-\-select"[=n]
+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
+\fB\-\-oneshot\fR behavior default.
+.TP
+.BR "\-\-selective"[=n]
This is similar to the \fB\-\-noreplace\fR option, except that it
does not take precedence over options such as \fB\-\-newuse\fR.
+Some options, such as \fB\-\-update\fR, imply \fB\-\-selective\fR.
+Use \fB\-\-selective=n\fR if you want to forcefully disable
+\fB\-\-selective\fR, regardless of options like \fB\-\-update\fR.
.TP
.BR "\-\-skipfirst"
This option is only valid when used with \fB\-\-resume\fR. It removes the
This is only really useful in combination with \fB\-\-emptytree\fR or
\fB\-\-update\fR and \fB\-\-deep\fR.
.TP
-.BR "\-\-usepkg " (\fB\-k\fR)
+.BR "\-\-unordered\-display"
+By default the displayed merge list is sorted using the
+order in which the packages will be merged. When
+\fB\-\-tree\fR is used together with this option, this
+constraint is removed, hopefully leading to a more
+readable dependency tree.
+.TP
+.BR "\-\-use\-ebuild\-visibility[=n]"
+Use unbuilt ebuild metadata for visibility
+checks on built packages.
+.TP
+.BR "\-\-usepkg[=n] " (\fB\-k\fR)
Tells emerge to use binary packages (from $PKGDIR) if they are available, thus
possibly avoiding some time\-consuming compiles. This option is useful for CD
installs; you can export PKGDIR=/mnt/cdrom/packages and then use this option to
have emerge "pull" binary packages from the CD in order to satisfy dependencies.
.TP
-.BR "\-\-usepkgonly " (\fB\-K\fR)
+.BR "\-\-usepkgonly[=n] " (\fB\-K\fR)
Tells emerge to only use binary packages (from $PKGDIR). All the binary
packages must be available at the time of dependency calculation or emerge
will simply abort. Portage does not use $PORTDIR when calculating dependency
flags, the output may be a little hard to understand at first. This section
explains the abbreviations.
.TP
-.B [blocks B ] app\-text/dos2unix (from pkg app\-text/hd2u\-0.8.0)
+.B [blocks B ] app\-text/dos2unix ("app\-text/dos2unix" is blocking app\-text/hd2u\-0.8.0)
Dos2unix is Blocking hd2u from being emerged. Blockers are defined when
two packages will clobber each others files, or otherwise cause some form
of breakage in your system. However, blockers usually do not need to be
\fBemerge\fR an ebuild, then all forms of masking will be ignored and
\fBemerge\fR will attempt to emerge the package.
.TP
+.BR backtracking
+When packages are masked for \fBbacktracking\fR, it means that the dependency
+resolver has temporarily masked them in order to avoid dependency conflicts
+and/or unsatisfied dependencies. This type of mask is typically accompanied
+by a message about a missed package update which has been skipped in order to
+avoid dependency conflicts and/or unsatisfied dependencies.
+.TP
.BR package.mask
The \fBpackage.mask\fR file primarily blocks the use of packages that cause
problems or are known to have issues on different systems. It resides in
versions of packages, you should update your
\fI/etc/portage/package.keywords\fR file to list the packages you want the
\'testing\' version. See \fBportage\fR(5) for more information.
+.TP
+.BR LICENSE
+The \fBLICENSE\fR variable in an \fBebuild\fR file can be used to mask
+packages based on licensing restrictions. \fBemerge\fR examines the
+\fBACCEPT_LICENSE\fR environment variable to allow or disallow the emerging
+of a package masked by \fBLICENSE\fR. See \fBmake.conf\fR(5) for information
+about \fBACCEPT_LICENSE\fR, and see \fBportage\fR(5) for information about
+\fI/etc/portage/package.license\fR.
+.TP
+.BR PROPERTIES
+The \fBPROPERTIES\fR variable in an \fBebuild\fR file can be used to mask
+packages based on properties restrictions. \fBemerge\fR examines the
+\fBACCEPT_PROPERTIES\fR environment variable to allow or disallow the emerging
+of a package masked by \fBPROPERTIES\fR. See \fBmake.conf\fR(5) for information
+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.
.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
projects / portage.git / blobdiff