Remove extended package set configuration docs.
[portage.git] / man / emerge.1
index df576ee10b16c10f37b1cd1cfd3cf14927227d73..ea1e735d493162b8745ec259e8a996d79a16fe4c 100644 (file)
@@ -1,4 +1,4 @@
-.TH "EMERGE" "1" "May 2011" "Portage VERSION" "Portage"
+.TH "EMERGE" "1" "Oct 2011" "Portage VERSION" "Portage"
 .SH "NAME"
 emerge \- Command\-line interface to the Portage system
 .SH "SYNOPSIS"
@@ -62,14 +62,11 @@ would like to query the owners of one or more files or directories.
 A \fIset\fR is a convenient shorthand for a large group of
 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
+"world" packages that are listed in \fB/var/lib/portage/world\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 the \fB/usr/share/portage/config/sets\fR directory. Note that a \fIset\fR
+\fBFILES\fR below for more information.] 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. Use the \fB\-\-list\-sets\fR action to display a list of
@@ -120,11 +117,7 @@ always be kept. They can be manually added to this set with \fIemerge
 \-\-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 @world\fR prior to depclean. Also note that
-depclean may break link level dependencies, especially when the
-\fB\-\-depclean\-lib\-check\fR option is disabled. Thus, it is
-recommended to use a tool such as \fBrevdep-rebuild\fR(1)
-in order to detect such breakage.
+\-\-deep @world\fR prior to depclean.
 
 \fBWARNING:\fR
 Inexperienced users are advised to use \fB\-\-pretend\fR with this
@@ -132,7 +125,10 @@ option in order to see a preview of which packages
 will be uninstalled. Always study the list of packages
 to be cleaned for any obvious mistakes. Note that packages listed in
 package.provided (see \fBportage\fR(5)) may be removed by
-depclean, even if they are part of the world set.
+depclean, even if they are part of the world set. Also note that
+depclean may break link level dependencies. Thus, it is
+recommended to use a tool such as \fBrevdep-rebuild\fR(1)
+in order to detect such breakage.
 
 Depclean serves as a dependency aware
 version of \fB\-\-unmerge\fR. When given one or more atoms, it will
@@ -174,10 +170,12 @@ In versions of portage >=2.1.5 the \-\-metadata action is totally unnecessary
 unless the user has enabled FEATURES="metadata-transfer" in \fBmake.conf\fR(5).
 .TP
 .BR "\-\-prune " (\fB\-P\fR)
-\fBWARNING: This action can remove important packages!\fR  Removes all but the
-highest installed version of a package from your system. Use \fB\-\-prune\fR
-together with \fB\-\-verbose\fR to show reverse dependencies or with
-\fB\-\-nodeps\fR to ignore all dependencies.
+Removes all but the highest installed version of a package from your
+system. Use \fB\-\-prune\fR together with \fB\-\-verbose\fR to show
+reverse dependencies or with \fB\-\-nodeps\fR to ignore all dependencies.
+\fBWARNING: This action can remove packages from your world file! Check
+the emerge output of the next \-\-depclean run carefully! Use
+\-\-depclean to avoid this issue.\fR
 .TP
 .BR \-\-regen
 Causes portage to check and update the dependency cache of all ebuilds in the 
@@ -304,9 +302,24 @@ the specified configuration file(s), or enable the
 \fBEMERGE_DEFAULT_OPTS\fR variable may be used to
 disable this option by default in \fBmake.conf\fR(5).
 .TP
+.BR "\-\-autounmask\-unrestricted\-atoms [ y | n ]"
+If \-\-autounmask is enabled, keyword and mask changes
+using the \'=\' operator will be written. With this
+option, \'>=\' operators will be used whenever possible.
+USE and license changes always use the latter behavior.
+.TP
+.BR "\-\-autounmask\-keep\-masks [ y | n ]"
+If \-\-autounmask is enabled, no package.unmask or ** keyword changes
+will be created. This leads to unsatisfied dependencies if
+no other solution exists.
+.TP
 .BR "\-\-autounmask\-write [ y | n ]"
 If \-\-autounmask is enabled, changes are written
 to config files, respecting \fBCONFIG_PROTECT\fR and \fB\-\-ask\fR.
+If the corresponding package.* is a file, the changes are appended to
+it, if it is a directory, changes are written to the lexicographically
+last file. This way it is always ensured that the new changes take
+precedence over existing changes.
 .TP
 .BR \-\-backtrack=COUNT
 Specifies an integer number of times to backtrack if
@@ -327,6 +340,11 @@ An alternative for already\-merged
 packages is to use \fBquickpkg\fR(1) which creates a tbz2 from the
 live filesystem.
 .TP
+.BR "\-\-buildpkg\-exclude " ATOMS
+A space separated list of package atoms for which
+no binary packages should be built. This option overrides all
+possible ways to enable building of binary packages.
+.TP
 .BR "\-\-buildpkgonly " (\fB\-B\fR)
 Creates binary packages for all ebuilds processed without actually
 merging the packages.  This comes with the caveat that all build-time 
@@ -361,6 +379,10 @@ be updated than would have otherwise been updated with the option disabled.
 Using \fB\-\-with\-bdeps=y\fR together with \fB\-\-complete\-graph\fR makes
 the graph as complete as possible.
 .TP
+.BR "\-\-complete\-graph\-if\-new\-ver < y | n >"
+Trigger the \fB\-\-complete\-graph\fR behavior if an installed package
+version will change (upgrade or downgrade). This option is enabled by default.
+.TP
 .BR \-\-config\-root=DIR
 Set the \fBPORTAGE_CONFIGROOT\fR environment variable.
 .TP
@@ -379,14 +401,19 @@ listed in the dependencies of a package.  Also see \fB\-\-with\-bdeps\fR for
 behavior with respect to build time dependencies that are not strictly
 required.
 .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.
+.BR "\-\-dynamic\-deps < y | n >"
+In dependency calculations, substitute the dependencies of installed
+packages with the dependencies of corresponding unbuilt ebuilds from
+source repositories. This causes the effective dependencies of
+installed packages to vary dynamically when source ebuild dependencies
+are modified. This option is enabled by default.
+
+\fBWARNING:\fR
+If you want to disable \-\-dynamic\-deps, then it may be necessary to
+first run \fBfixpackages\fR in order to get the best results. The
+\fBfixpackages\fR command performs two different operations that can
+also be performed separately by the `emaint \-\-fix moveinst` and
+`emaint \-\-fix movebin` commands (see \fBemaint\fR(1)).
 .TP
 .BR "\-\-emptytree " (\fB\-e\fR)
 Reinstalls target atoms and their entire deep
@@ -488,10 +515,7 @@ Skips the packages specified on the command\-line that have already
 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. 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.
+not remerge dependencies by default.
 .TP
 .BR "\-\-nospinner"
 Disables the spinner for the session.  The spinner is active when the
@@ -559,18 +583,16 @@ to be set in the \fBmake.conf\fR(5)
 \fBEMERGE_DEFAULT_OPTS\fR variable.
 .TP
 .BR "\-\-rebuild\-if\-new\-rev [ y | n ]"
-Rebuild packages when dependencies that are used at both build\-time and
-run\-time are built, if the dependency is not already installed with the
-same version and revision.
+Rebuild packages when build\-time dependencies are built from source, if the
+dependency is not already installed with the same version and revision.
 .TP
 .BR "\-\-rebuild\-if\-new\-ver [ y | n ]"
-Rebuild packages when dependencies that are used at both build\-time and
-run\-time are built, if the dependency is not already installed with the
-same version. Revision numbers are ignored.
+Rebuild packages when build\-time dependencies are built from source, if the
+dependency is not already installed with the same version. Revision numbers
+are ignored.
 .TP
 .BR "\-\-rebuild\-if\-unbuilt [ y | n ]"
-Rebuild packages when dependencies that are used at both build\-time and
-run\-time are built.
+Rebuild packages when build\-time dependencies are built from source.
 .TP
 .BR "\-\-rebuilt\-binaries [ y | n ]"
 Replace installed packages with binary packages that have
@@ -619,8 +641,7 @@ use \fBEMERGE_DEFAULT_OPTS\fR to make
 \fB\-\-oneshot\fR behavior default.
 .TP
 .BR "\-\-selective [ y | n ]"
-This is similar to the \fB\-\-noreplace\fR option, except that it
-does not take precedence over options such as \fB\-\-newuse\fR.
+This is identical to the \fB\-\-noreplace\fR option.
 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.
@@ -959,9 +980,6 @@ Zac Medico <zmedico@gentoo.org>
 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/
-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