-.TH "EMERGE" "1" "Jun 2007" "Portage 2.1.3" "Portage"
+.TH "EMERGE" "1" "Aug 2008" "Portage 2.2" "Portage"
.SH "NAME"
emerge \- Command\-line interface to the Portage system
.SH "SYNOPSIS"
\fB\-\-search\fR \fIsomestring\fR
.TP
.BR emerge
-\fB\-\-help\fR [\fBsystem\fR | \fBworld\fR | \fB\-\-sync\fR]
+\fB\-\-help\fR [\fB\-\-verbose\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
.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. Note that a \fIset\fR
+on the current configuration. The default set configuration is located
+in \fB/usr/share/portage/config/sets.conf\fR. Note that a \fIset\fR
is generally used in conjunction with \fB\-\-update\fR. When used as
arguments to \fBemerge\fR sets have to be prefixed with \fB@\fR to be
-recognized.
+recognized. Use the \fB\-\-list\-sets\fR action to display a list of
+available package sets.
.TP
.BR atom
An \fIatom\fR describes bounds on a package that you wish to install.
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 \-\-oneshot @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
\fB\-\-depclean\fR together with \fB\-\-verbose\fR to show reverse
dependencies.
.TP
+.BR "\-\-deselect[=n]"
+Remove atoms from the world file. This action is implied
+by uninstall actions, including \fB-\-depclean\fR,
+\fB-\-prune\fR and \fB-\-unmerge\fR. Use \fB-\-deselect=n\fR
+in order to prevent uninstall actions from removing
+atoms from the world file.
+.TP
.BR "\-\-help " (\fB\-h\fR)
Displays help information for emerge. Adding one of the additional
arguments listed above will give you more specific help information
information when submitting a bug report.\fR Expanded output can be obtained
with the \fI\-\-verbose\fR option.
.TP
+.BR \-\-list\-sets
+Displays a list of available package sets.
+.TP
.BR \-\-metadata
Transfers metadata cache from ${PORTDIR}/metadata/cache/ to
/var/cache/edb/dep/ as is normally done on the
the cache. After a portage update, rsync users may find it convenient to run
\fBemerge \-\-metadata\fR to rebuild the cache as portage does at the end of
a sync operation. In order to specify parallel \fB\-\-regen\fR behavior, use
-the \fB\-\-jobs\fR and \fB\-\-load\-average\fR options.
+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
+don't match the current configuration. (default: \'n\')
.TP
.BR "\-\-buildpkg " (\fB\-b\fR)
Tells emerge to build binary packages for all ebuilds processed in
addition to actually merging the packages. Useful for maintainers
or if you administrate multiple Gentoo Linux systems (build once,
emerge tbz2s everywhere) as well as disaster recovery. The package
-will be created in the
-\fI${PKGDIR}/All\fR directory. An alternative for already\-merged
+will be created in the \fBPKGDIR\fR directory (see \fBmake.conf\fR(5)).
+An alternative for already\-merged
packages is to use \fBquickpkg\fR(1) which creates a tbz2 from the
live filesystem.
.TP
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)
-This option is identical to \fB\-g\fR, as above, except it will not use ANY
-information from the local machine. All binaries will be downloaded from the
-remote server without consulting packages existing in the local packages
-directory.
+.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
.BR "\-\-ignore-default-opts"
Causes \fIEMERGE_DEFAULT_OPTS\fR (see \fBmake.conf\fR(5)) to be ignored.
.TP
-.BR \-\-jobs=JOBS
-Specifies the number of packages to build simultaneously. Also see
-the related \fB\-\-load\-average\fR option.
+.BR "-j [JOBS], \-\-jobs[=JOBS]"
+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.
been installed. Without this option, any packages, ebuilds, or deps
you specify on the command\-line \fBwill\fR cause Portage to remerge
the package, even if it is already installed. Note that Portage will
-not remerge dependencies by default.
+not remerge dependencies by default. Also note that this option takes
+precedence over options such as \fB\-\-newuse\fR, preventing a package
+from being reinstalled even though the corresponding USE flag settings
+may have changed.
.TP
.BR "\-\-nospinner"
Disables the spinner for the session. The spinner is active when the
have been installed if \fB\-\-pretend\fR weren't used. Using \fB\-\-pretend\fR
is strongly recommended before installing an unfamiliar package. In
the printout:
-.br
-
-.br
-\fIN\fR = new (not yet installed)
-.br
-\fIS\fR = new SLOT installation (side-by-side versions)
-.br
-\fIU\fR = updating (to another version)
-.br
-\fID\fR = downgrading (best version seems lower)
-.br
-\fIR\fR = replacing (remerging same version))
-.br
-\fIF\fR = fetch restricted (must be manually downloaded)
-.br
-\fIf\fR = fetch restricted (already downloaded)
-.br
-\fIB\fR = blocked by an already installed package
+
+.TS
+lI l.
+N new (not yet installed)
+S new SLOT installation (side-by-side versions)
+U updating (to another version)
+D downgrading (best version seems lower)
+R replacing (remerging same version))
+F fetch restricted (must be manually downloaded)
+f fetch restricted (already downloaded)
+I interactive (requires user input)
+B blocked by another package (unresolved conflict)
+b blocked by another package (automatically resolved conflict)
+.TE
.TP
.BR "\-\-quiet " (\fB\-q\fR)
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
not trigger reinstallation when flags that the user has not
enabled are added or removed.
.TP
+.BR \-\-root=DIR
+Set the \fBROOT\fR environment variable.
+.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"[=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
first package in the resume list. Dependencies are recalculated for
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
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
in order to indicate their status:
-.br
-.br
-\fI- prefix\fR = not enabled (either disabled or removed)
-.br
-\fI* suffix\fR = transition to or from the enabled state
-.br
-\fI% suffix\fR = newly added or removed
-.br
-\fI() circumfix\fR = forced, masked, or removed
+.TS
+l l l
+___
+l l l.
+Symbol Location Meaning
+
+- prefix not enabled (either disabled or removed)
+* suffix transition to or from the enabled state
+% suffix newly added or removed
+() circumfix forced, masked, or removed
+.TE
.TP
.BR "\-\-with\-bdeps < y | n >"
In dependency calculations, pull in build time dependencies
.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 in \fBmake.conf\fR(5)
-when \fBPORTAGE_CONFIGROOT\fR has a value other than /.
+merging packages or ebuilds. This variable can be set via the \fB\-\-root\fR
+option or in \fBmake.conf\fR(5) (the command line overrides other settings).
.br
Defaults to /.
.TP
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
.TP
.BR CHOST
Use the \fBACCEPT_CHOSTS\fR variable in \fBmake.conf\fR(5) to control
-\fBCHOST\fR acceptance for binary packages.
+\fBCHOST\fR acceptance.
.TP
.BR EAPI
The \fBEAPI\fR variable in an \fBebuild\fR(5) file is used to mask packages
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
Phil Bordelon <phil@thenexusproject.org>
Mike Frysinger <vapier@gentoo.org>
Marius Mauch <genone@gentoo.org>
+Jason Stubbs <jstubbs@gentoo.org>
+Brian Harring <ferringb@gmail.com>
+Zac Medico <zmedico@gentoo.org>
.fi
.SH "FILES"
Here is a common list of files you will probably be interested in. For a
complete listing, please refer to the \fBportage\fR(5) man page.
.TP
+.B /usr/share/portage/config/sets.conf
+Contains the default set configuration.
+.TP
.B /var/lib/portage/world
Contains a list of all user\-specified packages. You can safely edit
this file, adding packages that you want to be considered in \fBworld\fR
Contains profile\-specific variables for the build process. \fBDo not
edit this file\fR.
.TP
-.B /etc/make.profile/use.defaults
-Contains a list of packages which, if installed, cause the respective USE
-flag to be enabled by default. \fBDo not edit this file\fR.
-.TP
.B /usr/portage/profiles/use.desc
Contains the master list of USE flags with descriptions of their
functions. \fBDo not edit this file\fR.
projects / portage.git / blobdiff