diff options
Diffstat (limited to 'man/emerge.1')
| -rw-r--r-- | man/emerge.1 | 87 |
1 files changed, 57 insertions, 30 deletions
diff --git a/man/emerge.1 b/man/emerge.1 index 8f8c2ebda..dd9cde572 100644 --- a/man/emerge.1 +++ b/man/emerge.1 @@ -1,11 +1,11 @@ -.TH "EMERGE" "1" "Mar 2021" "Portage VERSION" "Portage" +.TH "EMERGE" "1" "Jan 2024" "Portage @VERSION@" "Portage" .SH "NAME" emerge \- Command\-line interface to the Portage system .SH "SYNOPSIS" .TP .BR emerge -[\fIoptions\fR] [\fIaction\fR] [\fIebuild\fR | \fItbz2file\fR | \fIfile\fR | -\fI@set\fR | \fIatom\fR] ... +[\fIoptions\fR] [\fIaction\fR] [\fIebuild\fR | \fItbz2 file\fR | \fIgpkg file\fR | +\fIfile\fR | \fI@set\fR | \fIatom\fR] ... .TP .BR emerge \fB\-\-sync\fR [\fIrepo\fR | \fIalias\fR] ... @@ -30,8 +30,8 @@ distribution. .SH "EBUILDS, TBZ2S, SETS AND ATOMS" \fBemerge\fR primarily installs packages. You can specify packages to install in five possible ways: an \fIatom\fR, -a \fIset\fR, an installed \fIfile\fR, an \fIebuild\fR, or -a \fItbz2file\fR. +a \fIset\fR, an installed \fIfile\fR, an \fIebuild\fR, a +a \fItbz2\fR file, or a \fIgpkg\fR file. .LP .TP .BR ebuild @@ -47,11 +47,17 @@ The \fIebuild\fR may also be an actual filename, such as \fBWARNING:\fR The implementation of \fBemerge /path/to/ebuild\fR is broken and so this syntax shouldn't be used. .TP -.BR tbz2file -A \fItbz2file\fR must be a valid .tbz2 created with \fBebuild +.BR "tbz2 file" +A \fItbz2\fR file must be a valid .tbz2 created with \fBebuild <package>\-<version>.ebuild package\fR or \fBemerge \-\-buildpkg [category/]<package>\fR or \fBquickpkg [category/]<package>\fR. .TP +.BR "gpkg file" +A \fIgpkg\fR file must be a valid .gpkg created with \fBebuild +<package>\-<version>.ebuild package\fR or \fBemerge \-\-buildpkg +[category/]<package>\fR or \fBquickpkg [category/]<package>\fR +with \fBBINPKG_FORMAT="gpkg"\fR. +.TP .BR file A \fIfile\fR must be a file or directory that has been installed by one or more packages. If an absolute path is not used, then it must begin with @@ -99,9 +105,9 @@ specific \fBSLOT\fR by appending a colon and a \fBSLOT\fR. Example: If no action is specified, the action is to merge in the specified packages, satisfying any dependencies that they may have. The arguments can be \fIatoms\fR, \fIsets\fR, installed \fIfiles\fR, -\fIebuilds\fR, or \fItbz2s\fR. +\fIebuilds\fR, \fItbz2s\fR, or \fIgpkgs\fR. \fBNote that you need to use the \-\-usepkg -option if you want to install a tbz2\fR. The packages are added +option if you want to install a tbz2 or a gpkg.\fR The packages are added to the \fBworld\fR file at the end, so that they are considered for later updating. .TP @@ -434,33 +440,35 @@ precedence over existing changes. This option is automatically enabled with .BR \-\-backtrack=COUNT Specifies an integer number of times to backtrack if dependency calculation fails due to a conflict or an -unsatisfied dependency (default: \'10\'). +unsatisfied dependency (default: \'20\'). .TP .BR "\-\-binpkg\-changed\-deps [ y | n ]" Tells emerge to ignore binary packages for which the corresponding ebuild dependencies have changed since the packages were built. In order to help avoid issues with resolving inconsistent dependencies, this option is automatically enabled unless the \fB\-\-usepkgonly\fR -option is enabled. Behavior with respect to changed build\-time +(or \fB\-\-getbinpkgonly\fR) option is enabled. +Behavior with respect to changed build\-time dependencies is controlled by the \fB\-\-with\-bdeps\fR option. .TP .BR "\-\-binpkg\-respect\-use [ y | n ]" Tells emerge to ignore binary packages if their USE flags don't match the current configuration. In order to help avoid issues with resolving inconsistent USE flag settings, this option is -automatically enabled unless the \fB\-\-usepkgonly\fR option -is enabled. If \fB\-\-binpkg\-respect\-use\fR is given explicitly, +automatically enabled unless the \fB\-\-usepkgonly\fR +(or \fB\-\-getbinpkgonly\fR) option is enabled. +If \fB\-\-binpkg\-respect\-use\fR is given explicitly, then it implies \fB\-\-autounmask\-use=n\fR, because these options -naturally oppose eachother. +naturally oppose each other. .TP .BR "\-\-buildpkg [ y | n ]" ", " \-b 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 +emerge tbz2s or gpkgs everywhere) as well as disaster recovery. The package 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 +packages is to use \fBquickpkg\fR(1) which creates a tbz2 or gpkg from the live filesystem. .TP .BR \-\-buildpkg\-exclude " ATOMS" @@ -507,9 +515,10 @@ has a special binding to FEATURES="test" (see \fBmake.conf\fR(5) for more information about \fBFEATURES\fR settings). .TP .BR "\-\-color < y | n >" -Enable or disable color output. This option will override \fINOCOLOR\fR -(see \fBmake.conf\fR(5)) and may also be used to force color output when stdout -is not a tty (by default, color is disabled unless stdout is a tty). +Enable or disable color output. This option will override \fINO_COLOR\fR +and \fINOCOLOR\fR (see \fBmake.conf\fR(5)) and may also be used to force +color output when stdout is not a tty (by default, color is disabled +unless stdout is a tty). .TP .BR \-\-columns Used alongside \fB\-\-pretend\fR to cause the package name, new version, @@ -588,7 +597,7 @@ dependency tree, as though no packages are currently installed. You should run this with \fB\-\-pretend\fR first to make sure the result is what you expect. .TP -.BR "\-\-exclude " ATOMS +.BR "\-\-exclude, \-X ATOMS" A space separated list of package names or slot atoms. Emerge won't install any ebuild or binary package that matches any of the given package atoms. @@ -647,7 +656,7 @@ that can pull unbuilt ebuilds into the dependency graph, since unbuilt ebuilds do not have any soname dependency metadata, making it impossible to determine whether an unresolved soname dependency can be satisfied. Therefore, \fB\-\-usepkgonly\fR (or \fB\-\-getbinpkgonly\fR) must be -used in order to enable soname depedency resolution when installing +used in order to enable soname dependency resolution when installing packages. .TP .BR "\-\-ignore\-world [ y | n ]" @@ -671,7 +680,7 @@ this option. Assume that packages may have implicit dependencies on packages which belong to the @system set. This option is enabled by default. One of the effects of disabling this option is to allow the \-\-jobs option to -spawn jobs without accounting for the possiblity of implicit dependencies +spawn jobs without accounting for the possibility of implicit dependencies on packages that belong to the @system set. .TP .BR \-j\ [JOBS] ", " \-\-jobs[=JOBS] @@ -740,7 +749,8 @@ file to always be merged. .TP .BR \-\-nodeps ", " \-O Merges specified packages without merging any dependencies. Note that -the build may fail if the dependencies aren't satisfied. +the build may fail if the dependencies aren't satisfied. This option +implies \fB--backtrack=0\fR. .TP .BR \-\-noreplace ", " \-n Skips the packages specified on the command\-line that have already @@ -794,6 +804,11 @@ Include run time dependencies when \fB\-\-onlydeps\fR is specified. When this is disabled only build time dependencies are included. This option is enabled by default. .TP +.BR "\-\-onlydeps\-with\-ideps < y | n >" +Include install time dependencies when \fB\-\-onlydeps\fR and +\fB\-\-onlydeps\-with\-rdeps=n\fR are both specified. This option is +disabled by default. +.TP .BR "\-\-package\-moves [ y | n ]" Perform package moves when necessary. This option is enabled by default. Package moves are typically applied immediately @@ -919,7 +934,7 @@ 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), +dependencies (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. @@ -1043,6 +1058,12 @@ the command line are greedy, meaning that unspecific atoms may match multiple versions of slotted packages. This option also implies the \fB\-\-selective\fR option. .TP +.BR \-\-update\-if\-installed +Acts similar to \fB\-\-update\fR except it updates packages +passed as arguments to the best version available only if they are +already installed. This is useful for oneshot commands across +a series of systems to upgrade away from a buggy version. +.TP .BR "\-\-use\-ebuild\-visibility [ y | n ]" Use unbuilt ebuild metadata for visibility checks on built packages. @@ -1056,13 +1077,19 @@ 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. +dependencies. Note this option implies \fB\-\-with\-bdeps=n\fR. To include +build time dependencies, \fB\-\-with\-bdeps=y\fR must be specified explicitly. .TP .BR "\-\-usepkgonly [ y | n ]" ", " \-K 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 ebuild repositories when calculating -dependency information so all masking information is ignored. +dependency information so all masking information is ignored. Like \fB\-k\fR +above, this option implies \fB\-\-with\-bdeps=n\fR. To include build time +dependencies, \fB\-\-with\-bdeps=y\fR must be specified explicitly. +.TP +.BR "\-\-usepkg\-exclude\-live [ y | n ]" +Tells emerge to not install from binary packages for live ebuilds. .TP .BR "\-\-verbose [ y | n ]" ", " \-v Tell emerge to run in verbose mode. Currently this flag causes emerge to print @@ -1266,10 +1293,10 @@ Symbol Mask Type # package.mask * missing keyword -~ unstable keyword +\(ti unstable keyword .TE -\fBNOTE:\fR The unstable keyword symbol (~) will not be shown in cases +\fBNOTE:\fR The unstable keyword symbol (\(ti) will not be shown in cases in which the corresponding unstable keywords have been accepted globally via \fBACCEPT_KEYWORDS\fR. .TP @@ -1304,7 +1331,7 @@ permanent, you can put them in /etc/portage/package.use instead. If \fBemerge \-\-update @system\fR or \fBemerge \-\-update @world\fR fails with an error message, it may be that an ebuild uses some newer feature not present in this version of \fBemerge\fR. You -can use \fBemerge \-\-update sys-apps/portage\fR to upgrade to the lastest +can use \fBemerge \-\-update sys-apps/portage\fR to upgrade to the latest version, which should support any necessary new features. .SH "MASKED PACKAGES" \fINOTE: Please use caution when using development packages. Problems @@ -1346,7 +1373,7 @@ The \fBKEYWORDS\fR variable in an \fBebuild\fR file is also used for masking a package still in testing. There are architecture\-specific keywords for each package that let \fBportage\fR know which systems are compatible with the package. Packages which compile on an architecture, but have not been -proven to be "stable", are masked with a tilde (\fB~\fR) in front of the +proven to be "stable", are masked with a tilde (\fB\(ti\fR) in front of the architecture name. \fBemerge\fR examines the \fBACCEPT_KEYWORDS\fR environment variable to allow or disallow the emerging of a package masked by \fBKEYWORDS\fR. To inform \fBemerge\fR that it should build these 'testing' |