.TH "EBUILD" "1" "Dec 2005" "Portage 2.1" "Portage"
.SH "NAME"
-ebuild \- manual page for the ebuild program, a low level interface to
-the Portage system.
+ebuild \- a low level interface to the Portage system
.SH "SYNOPSIS"
.B ebuild
.I file command [command]\fR...
The ebuild program is a direct interface to the Portage system. It
allows for direct action upon an ebuild with specific subcommands or
groups of commands to perform in a specific ebuild's context and
-functions. Accepting an ebuild script and one or more commands
+functions. Accepting an ebuild script and one or more commands
as arguments, the ebuild program parses the ebuild script and
-execute the specified commands. Commands exist to fetch sources,
+executes the specified commands. Commands exist to fetch sources,
unpack sources, compile sources, install object files into a temporary
directory "image", merge the image to the local filesystem, create a
bzipped tarball package out of the image, and more.
.SH "COMMANDS"
.TP
.BR help
-Show a condensed form of the man page along with a lot of package
+Shows a condensed form of this man page along with a lot of package
specific information.
.TP
.BR setup
-Run all package specific setup actions and exotic system checks.
+Runs all package-specific setup actions and exotic system checks.
.TP
.BR clean
Cleans the temporary build directory that Portage has created for
this variable, see \fBmake.conf\fR(5).
Note: Portage cleans up almost everything after a package has been
-successfully merged unless FEATURES contains 'noclean'. Adding noclean
+successfully merged unless FEATURES contains 'noclean'. Adding noclean
to FEATURES will cause a lot of files to remain and will consume large
-amounts of space, very quickly. It is not recommended to leave this on
-unless you have use for the sources post\-merge. Optionally one may,
-manual clean \fIrm \-rf /var/tmp/portage\fR will take care of all
-of these files.
+amounts of space, very quickly. It is not recommended to leave this on,
+unless you have use for the sources post\-merge. Optionally, one may
+manually clean these files with \fIrm \-rf /var/tmp/portage\fR.
.TP
.BR fetch
Checks to see if all the sources specified in SRC_URI are available in
download locations are listed for a particular file, Portage pings
each location to see which location is closer. (May not be true
presently.) The Gentoo Linux mirrors defined by GENTOO_MIRRORS is
-always considered first. If for some reason the current or
+always considered first. If for some reason the current or
just\-downloaded sources' md5 digests don't match those recorded
in files/digest\-[package]\-[version\-rev], a warning is printed
and ebuild exits with an error code of 1.
.TP
.BR digest
Creates a digest file for the package in
-/usr/portage/[category]/[package]/files/. This digest file lists the
-md5sum's of all the files found in the SRC_URI. If the fetched source
+/usr/portage/[category]/[package]/files/. This digest file lists the
+md5sums of all the files found in the SRC_URI. If the fetched source
of the package is corrupt/bogus in some way, the md5sum will catch this.
.TP
.BR manifest
file. If no src_unpack() function has been specified, a default
src_unpack() function is used that extracts all the files specified in
SRC_URI. The sources are normally extracted to
-${BUILD_PREFIX}/[package]\-[version\-rev]/work. This particular directory
+${BUILD_PREFIX}/[package]\-[version\-rev]/work. This particular directory
can be referenced by using the ${WORKDIR} variable.
If you're creating an ebuild, you'll want to make sure that the S
-(source directory) variable defined at at the top of your ebuild script
-points to the directory that contains your extracted sources. This
+(source directory) variable defined at the top of your ebuild script
+points to the directory that contains your extracted sources. This
directory is defined by default to be ${WORKDIR}/${P}, so it is not
often required. The src_unpack() function is also responsible for
making the appropriate patches to the sources so that they're ready
for compilation.
.TP
.BR compile
-Compiles the extracted sources by running the the \fIsrc_compile()\fR
+Compiles the extracted sources by running the \fIsrc_compile()\fR
function specified in the ebuild file. When src_compile() starts, the
current working directory will be set to ${S}. When src_compile()
completes, the sources should be fully compiled.
.TP
.BR test
-Run package specific test cases to verify that everything was built
+Runs package-specific test cases to verify that everything was built
properly.
.TP
.BR preinst
-Run package specific actions that need to be done before the package
+Runs package-specific actions that need to be done before the package
is installed into the live filesystem.
.TP
.BR install
the \fIsrc_install()\fR function. When completed, the
\fIinstall directory\fR (${BUILD_PREFIX}/[package]\-[version\-rev]/image)
will contain all the files that should either be merged to the local
-file system or included in a binary package.
+filesystem or included in a binary package.
.TP
.BR postinst
-Run package specific actions that need to be done after the package
+Runs package-specific actions that need to be done after the package
is installed into the live filesystem. Usually helpful messages are
shown here.
.TP
.BR qmerge
This function installs all the files in the \fIinstall directory\fR
-to the live filesystem. The process works as follows: first, the
+to the live filesystem. The process works as follows: first, the
\fIpkg_preinst()\fR function (if specified) is run. Then, the files
are merged into the live filesystem, and the installed files' md5
digests are recorded in
-\fI/var/db/pkg/${CATEOGRY}/${PN}\-[version\-rev]/CONTENTS\fR. After
+\fI/var/db/pkg/${CATEGORY}/${PN}\-${PVR}/CONTENTS\fR. After
all the files have been merged, the \fIpkg_postinst()\fR function
(if specified) is executed.
.TP
particular step doesn't complete successfully.
.TP
.BR unmerge
-This function first executes the \fIpkg_prerm\fR function (if specified).
+This function first executes the \fIpkg_prerm()\fR function (if specified).
Then it removes all files from the live filesystem that have a valid md5
checksum and mtime in the package contents file. Any empty directories
-are recursively removed. Finally, it runs \fIpkg_postrm\fR function (if
+are recursively removed. Finally, it runs \fIpkg_postrm()\fR function (if
specified). It is safe to merge a new version of a package first and
then unmerge the old one. In fact, this is the recommended package
upgrade method.
.TP
.BR prerm
-Run package specific actions that need to be executed before the package is
+Runs package-specific actions that need to be executed before the package is
removed from the filesystem. See also \fIunmerge\fR.
.TP
.BR postrm
-Run package specific actions that need to be executed after the package is
+Runs package-specific actions that need to be executed after the package is
removed from the filesystem. See also \fIunmerge\fR.
.TP
.BR config
-Run package specific actions needed to be executed after the emerge
-process has completed. This usually entails configuration file
-setup or other similar setups that the user may wish to run.
+Runs package-specific actions that need to be executed after the emerge
+process has completed. This usually entails setup of configuration files
+or other similar setups that the user may wish to run.
.TP
.BR package
This command is a lot like the \fImerge\fR command, except that after
.TP
.BR rpm
Builds a RedHat RPM package from the files in the temporary
-\fIinstall directory\fR. At the moment, the ebuild's dependency
+\fIinstall directory\fR. At the moment, the ebuild's dependency
information is not incorporated into the RPM.
.SH "REPORTING BUGS"
Please report bugs via http://bugs.gentoo.org/
operation that does not involve the helper tools and functions (found below)
should be prefixed with ${D}. Do not modify this variable.
.TP
+\fBROOT\fR = \fI"/"\fR
+Contains the path that portage should use as the root of the live filesystem.
+When packages wish to make changes to the live filesystem, it should do so in
+the tree prefixed by ${ROOT}. Do not modify this variable.
+.TP
\fBDESCRIPTION\fR = \fI"A happy little package"\fR
Should contain a short description of the package.
.TP
\fBSRC_URI\fR = \fI"http://happy.com/little/${P}.tar.gz"\fR
Contains a list of URI's for the required source files. It can contain
multiple URI's for a single source file. The list is processed in order
-if the file was not found on any of the \fIGENTOO_MIRROR\fRs.
+if the file was not found on any of the \fIGENTOO_MIRRORS\fR.
.TP
\fBHOMEPAGE\fR = \fI"http://happy.com/"\fR
Should contain a list of URL's for the sources main sites and other further
.PD 0
.RS
.TP
+.I binchecks
+Disable all QA checks for binaries (do not use without very good reason). See
+the \fBQA CONTROL VARIABLES\fR section for more specific exemptions.
+.TP
+.I confcache
+Prevent econf from using confcache.
+.TP
.I fetch
like \fImirror\fR but the files will not be fetched via \fBSRC_URI\fR either.
.TP
For example, blackdown-jdk and sun-jdk provide \fIvirtual/jdk\fR. This
allows for packages to depend on \fIvirtual/jdk\fR rather than on blackdown
or sun specifically.
+.SH "QA CONTROL VARIABLES"
+.TP
+.B USAGE NOTES
+Several QA variables are provided which allow an ebuild to manipulate some
+of the QA checks performed by portage. Use of these variables in ebuilds
+should be kept to an absolute minimum otherwise they defeat the purpose
+of the QA checks, and their use is subject to agreement of the QA team.
+They are primarily intended for use by ebuilds that install closed-source
+binary objects that cannot be altered.
+.br
+Note that objects that violate these rules may fail on some architectures.
+.TP
+\fBQA_TEXTRELS\fR
+This variable can be set to a list of file paths, relative to the image
+directory, of files that contain text relocations that cannot be eliminated.
+The paths may contain regular expressions.
+.br
+This variable is intended to be used on closed-source binary objects that
+cannot be altered.
+.TP
+\fBQA_EXECSTACK\fR
+This should contain a list of file paths, relative to the image directory, of
+objects that require executable stack in order to run.
+The paths may contain regular expressions.
+.br
+This variable is intended to be used on objects that truly need executable
+stack (i.e. not those marked to need it which in fact do not).
+.TP
+\fBQA_WX_LOAD\fR
+This should contain a list of file paths, relative to the image directory, of
+files that contain writable and executable segments. These are rare.
+The paths may contain regular expressions.
.SH "PORTAGE DECLARATIONS"
.TP
.B inherit
\fBbest_version\fR \fI<package name>\fR
This function will look up \fIpackage name\fR in the database of currently
installed programs and echo the "best version" of the package that is
-currently installed. The function returns 0 if there is a package that
-matches \fIpackage name\fR. Otherwise, the function will return 1.
+currently installed.
.RS
.TP
.I Example:
.RE
.PD 1
.TP
-\fBdopython\fR \fI<commands>\fR
-Performs \fIcommands\fR with python and returns the result.
-.TP
\fBdosed\fR \fI"s:orig:change:g" <filename>\fR
Performs sed (including cp/mv \fIfilename\fR) on \fIfilename\fR.
.br
Installs info\-pages into \fIDESTDIR\fR/info. Files are automatically
gzipped. Creates all necessary dirs.
.TP
-\fBdojar\fR \fI<jar file> [list of more jar files]\fR
-Installs jar files into /usr/share/${PN}/lib and adds them to
-/usr/share/${PN}/classpath.env.
-.TP
\fBdomo\fR \fI<locale-file> [list of more locale\-files] \fR
Installs locale\-files into \fIDESTDIR\fR/usr/share/locale/[LANG]
depending on local\-file's ending. Creates all necessary dirs.
ignores a trailing slash so that filename completion can be used.
The \fIebuild\fR may also be an actual filename, such as
\fB/usr/portage/app\-admin/python/python\-2.2.1\-r2.ebuild\fR.
-WARNING: The implementation of \fBemerge /path/to/ebuild\fR is broken and so this syntax shouldn't be used.
+WARNING: 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
[category/]<package>\fR or \fBquickpkg /var/db/pkg/<category>/<package>\fR.
.TP
.BR set
-Package sets are a convenient shorthand for large groups of
+A \fIset\fR is a convenient shorthand for a large group of
packages. Two sets are currently supported: \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 of the packages in \fBsystem\fR, along with any
+contains all the packages in \fBsystem\fR, plus any
other packages listed in \fB/var/lib/portage/world\fR. [See
-\fBFILES\fR below for more information.] Note that these
-commands are generally used in conjunction with \fB\-\-update\fR.
+\fBFILES\fR below for more information.] Note that a \fIset\fR
+is generally used in conjunction with \fB\-\-update\fR.
.TP
.BR dependency
A \fIdependency\fR describes bounds on a package that you wish to install.
specific version of Mozilla. This is generally safe to use.
\fBNote that\fR \-\-clean \fBdoes not remove unslotted packages.\fR
.TP
+.BR "\-\-config "
+Run package specific actions needed to be executed after the emerge process
+has completed. This usually entails configuration file setup or other similar
+setups that the user may wish to run.
+.TP
.BR \-\-depclean
Determines all packages installed on the system that have no
explicit reason for being there. \fBemerge\fR generates a list
and then unmerged after a short timeout. \fBWARNING: Removing some
packages may cause packages which link to the removed package
to stop working and complain about missing libraries.\fR
-Re\-emerge the complaining package to fix this issue.
-\fBNote that changes in USE flags can drastically affect the
-output of \-\-depclean.\fR
+Re\-emerge the complaining package to fix this issue. Also see
+\fB\-\-with\-bdeps\fR for behavior with respect to build time dependencies that
+are not strictly required.
.TP
.BR "\-\-help " (\fB\-h\fR)
Displays help information for emerge. Adding one of the additional
are having problems that this man page does not help resolve.
.TP
.BR \-\-info
-This is a list of information to include in bug reports which aids the
-developers with fixing any problems you may report. \fBPlease include this
+Produces a list of information to include in bug reports which aids the
+developers when fixing the reported problem. \fBPlease include this
information when submitting a bug report.\fR Expanded output can be obtained
with the \fI\-\-verbose\fR option.
.TP
.TP
.BR "\-\-search " (\fB\-s\fR)
Searches for matches of the supplied string in the portage tree.
-The \-\-search string is a regular expression. For example, \fBemerge
-\-\-search "^kde"\fR searches for any package that starts with "kde";
-\fBemerge \-\-search "gcc$"\fR searches for any package that ends with
-"gcc"; \fBemerge \-\-search "office"\fR searches for any package that
-contains the word "office". If you want to search the package
-descriptions as well, use the \fB\-\-searchdesc\fR action.
+By default emerge uses a case-insensitive simple search, but you can
+enable a regular expression search by prefixing the search string with %.
+For example, \fBemerge \-\-search "%^kde"\fR searches for any package whose
+name starts with "kde"; \fBemerge \-\-search "%gcc$"\fR searches for any
+package that ends with "gcc"; \fBemerge \-\-search "office"\fR searches for
+any package that contains the word "office". If you want to include the
+category into the search string, prepend an @: \fBemerge --search
+"%@^dev-java.*jdk"\fR. If you want to search the package descriptions as well,
+use the \fB\-\-searchdesc\fR action.
.TP
.BR "\-\-searchdesc " (\fB\-S\fR)
Matches the search string against the description field as well as
.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. In general,
-use this option only in combination with the world or system target.
+also update direct dependencies which may not be what you want. Package atoms
+specified on the command line are greedy, meaning that unspecific atoms may
+match multiple installed versions of slotted packages.
.TP
.BR "\-\-version " (\fB\-V\fR)
Displays the version number of \fBemerge\fR.
-.TP
-.BR "\-\-config "
-Run package specific actions needed to be executed after the
-emerge process has completed. This usually entails configuration
-file setup or other similar setups that the user may wish to run.
.SH "OPTIONS"
.TP
.BR "\-\-alphabetical "
continue with the merge or abort. Using \fB\-\-ask\fR is more efficient than
using \fB\-\-pretend\fR and then executing the same command without
\fB\-\-pretend\fR, as dependencies will only need to be calculated once.
+\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
.TP
.BR "\-\-buildpkg " (\fB\-b\fR)
Tells emerge to build binary packages for all ebuilds processed in
\fB\-\-debug\fR is great for finding bash syntax errors.
.TP
.BR "\-\-deep " (\fB\-D\fR)
-When used in conjunction with \fB\-\-update\fR, this flag forces
+This flag forces
\fBemerge\fR to consider the entire dependency tree of packages,
instead of checking only the immediate dependencies of the packages.
As an example, this catches updates in libraries that are not directly
-listed in the dependencies of a package.
+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 "\-\-emptytree " (\fB\-e\fR)
Reinstalls all world packages and their dependencies to the current USE
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.)
+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
was compiled.
.TP
.BR "\-\-nocolor "
-Make sure none of the output from portage contains color.
+Suppresses all coloring of portage's output.
.TP
.BR "\-\-noconfmem"
Causes portage to disregard merge records indicating that a config file
Instead of actually performing the merge, simply display what *would*
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,
+the printout:
.br
.br
-\fIN\fR = new, (not yet installed)
+\fIN\fR = new (not yet installed)
.br
-\fIS\fR = new, SLOT installation (side-by-side versions)
+\fIS\fR = new SLOT installation (side-by-side versions)
.br
-\fIU\fR = updating, (changing versions)
+\fIU\fR = updating (to another version)
.br
-\fID\fR = downgrade, (Best version seems lower)
+\fID\fR = downgrading (best version seems lower)
.br
-\fIR\fR = replacing, (Remerging same version))
+\fIR\fR = replacing (remerging same version))
.br
-\fIF\fR = fetch restricted, (Manual download)
+\fIF\fR = fetch restricted (must be manually downloaded)
.br
-\fIf\fR = fetch restricted, (Already downloaded)
+\fIf\fR = fetch restricted (already downloaded)
.br
\fIB\fR = blocked by an already installed package
.TP
\fB\-\-update\fR and \fB\-\-deep\fR.
.TP
.BR "\-\-usepkg " (\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.
+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)
Tells emerge to only use binary packages (from $PKGDIR). All the binary
information so all masking information is ignored.
.TP
.BR "\-\-verbose " (\fB\-v\fR)
-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.
+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
+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
+.TP
+.BR "\-\-with\-bdeps < y | n >"
+In dependency calculations, pull in build time dependencies that are not
+strictly required. This defaults to \'n\' for installation actions and
+\'y\' for the \-\-depclean action. This setting can be added to
+EMERGE_DEFAULT_OPTS (see make.conf(5)) and later overridden via the command
+line.
.SH "ENVIRONMENT OPTIONS"
.TP
\fBROOT\fR = \fI[path]\fR
merging packages or ebuilds.
.br
Defaults to /.
-.SH "ENVIRONMENT OPTIONS"
.TP
-\fBROOT\fR = \fI[path]\fR
-Use \fBROOT\fR to specify the target root filesystem to be used for
-merging packages or ebuilds.
+\fBPORTAGE_CONFIGROOT\fR = \fI[path]\fR
+Use \fBPORTAGE_CONFIGROOT\fR to specify the location for various portage
+configuration files
+(see \fBFILES\fR for a detailed list).
.br
Defaults to /.
.SH "OUTPUT"
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
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' 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.
+variable to allow or disallow the emerging of a package masked by
+\fBKEYWORDS\fR. To inform \fBemerge\fR that it should build these 'testing'
+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.
.SH "REPORTING BUGS"
Please report any bugs you encounter through our website:
.LP
.br
Defaults to 5 seconds.
.TP
-\fBCONFIG_PROTECT\fR = \fI[space delimited list of dirs]\fR
-All directories that are defined here will have "config file protection"
+\fBCOLLISION_IGNORE\fR = \fI[space delimited list of files and/or directories]\fR
+This variable allows the user to disable \fIcollision\-protect\fR for specific
+files and/or directories.
+.TP
+\fBCONFIG_PROTECT\fR = \fI[space delimited list of files and/or directories]\fR
+All files and/or directories that are defined here will have "config file protection"
enabled for them. For more information, please see `emerge \-\-help config`.
.TP
-\fBCONFIG_PROTECT_MASK\fR = \fI[space delimited list of dirs]\fR
-All directories that are defined here will have "config file protection"
+\fBCONFIG_PROTECT_MASK\fR = \fI[space delimited list of files and/or directories]\fR
+All files and/or directories that are defined here will have "config file protection"
disabled for them. For more information, please see `emerge \-\-help config`.
.TP
.B CTARGET
Defines whether or not to ignore short pauses that occur when displaying
important informational messages. This variable is unset by default.
.TP
-\fBFEATURES\fR = \fI"sandbox ccache autoaddcvs"\fR
+\fBFEATURES\fR = \fI"sandbox ccache"\fR
Defines actions portage takes by default. These options should
not be changed by anyone but developers and/or maintainers. 'sandbox' is an important
part of \fBFEATURES\fR and should not be disabled by default. This is
.TP
.B assume-digests
When commiting work to cvs with \fBrepoman\fR(1), assume that all existing
-SRC_URI digests are correct.
-.TP
-.B autoaddcvs
-Causes portage to automatically try to add files to cvs that will have to be added
-later. Done at generation times and only works when \fIcvs\fR is also in
-\fBFEATURES\fR.
+SRC_URI digests are correct. This feature also affects digest generation via
+\fBebuild\fR(1) and \fBemerge\fR(1) (emerge generates digests only when the
+\fIdigest\fR feature is enabled).
.TP
.B buildpkg
Binary packages will be created for all packages that are merged.
.TP
+.B buildsyspkg
+Build binary packages for just packages in the system set.
+.TP
.B ccache
Enable portage support for the ccache package. If the ccache dir is not
present in the user's environment, then portage will default to
.TP
.B confcache
Enable confcache support; global configure caching, speeds up autotool based configure
-calls.
+calls via the econf helper function. See \fBebuild\fR(5) for more information.
.TP
.B collision\-protect
A QA\-feature to ensure that a package doesn't overwrite files it doesn't own.
+The \fICOLLISION_IGNORE\fR variable can be used to selectively disable this
+feature.
.TP
.B cvs
A feature for developers that causes portage to enable all USE flags in SRC_URI
when creating digests.
.TP
.B digest
-Autogenerate a digest for packages.
+Autogenerate digests for packages when running the \fBemerge\fR(1) command. If
+the \fIassume-digests\fR feature is also enabled then existing SRC_URI digests
+will be reused whenever they are available.
.TP
.B distcc
Enable portage support for the distcc package.
.B gpg
Check the signatures of Manifests and make sure they are correct.
.TP
+.B installsources
+Install source code into /usr/src/debug/${CATEGORY}/${PF} (also see
+\fBsplitdebug\fR). This feature works only if debugedit is installed.
+.TP
.B keeptemp
Do not delete the ${T} directory after the merge process.
.TP
.TP
.B splitdebug
Prior to stripping ELF etdyn and etexec files, the debugging info is
-stored for later use by various debuggers.
+stored for later use by various debuggers. This feature is disabled by
+\fBnostrip\fR. For installation of source code, see \fBinstallsources\fR.
.TP
.B strict
Have portage react strongly to conditions that have the potential to be
dangerous (like missing or incorrect Manifests).
.TP
+.B stricter
+Have portage react strongly to conditions that may conflict with system
+security provisions (for example textrels, executable stack). Read about
+the \fIQA_STRICT_*\fR variables in \fBmake.conf\fR(5).
+.TP
.B suidctl
Before merging packages to the live filesystem, automatically strip setuid
bits from any file that is not listed in \fI/etc/portage/suidctl.conf\fR.
the package compiled properly. See \fItest\fR in \fBebuild\fR(1)
and \fIsrc_test()\fR in \fBebuild\fR(5).
.TP
+.B userfetch
+When portage is run as root, drop privileges to portage:portage during the
+fetching of package sources.
+.TP
.B userpriv
-Allow portage to drop root privledges and compile packages as
+Allow portage to drop root privileges and compile packages as
portage:portage without a sandbox (unless \fIusersandbox\fR is also used).
.TP
.B usersandbox
internet by \fBwget\fR(1). They are only required if you use a
proxy server for internet access.
.TP
+\fBINSTALL_MASK\fR = \fI[space delimited list of file names]\fR
+Use this variable if you want to selectively prevent certain files from being
+copied into your file system tree. This does not work on symlinks, but only on
+actual files. Useful if you wish to filter out files like HACKING.gz and
+TODO.gz.
+.TP
.B MAKEOPTS
Use this variable if you want to use parallel make. For example, if you
have a dual\-processor system, set this variable to "\-j2" or "\-j3" for
have been partially downloaded. It should be defined using the same format
as \fBFETCHCOMMAND\fR.
.TP
+\fBQA_STRICT_EXECSTACK = \fI"set"\fR
+Set this to cause portage to ignore any \fIQA_EXECSTACK\fR override
+settings from ebuilds. See also \fBebuild\fR(5).
+.TP
+\fBQA_STRICT_WX_LOAD = \fI"set"\fR
+Set this to cause portage to ignore any \fIQA_WX_LOAD\fR override
+settings from ebuilds. See also \fBebuild\fR(5).
+.TP
+\fBQA_STRICT_TEXTRELS = \fI"set"\fR
+Set this to cause portage to ignore any \fIQA_TEXTREL\fR override
+settings from ebuilds. See also \fBebuild\fR(5).
+.TP
\fBROOT\fR = \fI[path]\fR
Use \fBROOT\fR to specify the target root filesystem to be used for merging
packages or ebuilds. All \fBRDEPEND\fR and \fBPDEPEND\fR will be installed
into \fBROOT\fR while all \fBDEPEND\fR will be still be installed into /.
Typically, you should set this setting in the environment rather than in
\fI/etc/make.conf\fR itself. It's commonly used for creating new build
-images.
+images. Make sure you use an absolute path.
.br
Defaults to /.
.TP
packages. More information in \fBebuild\fR(5). Possible USE values
can be found in \fI/usr/portage/profiles/use.desc\fR.
.TP
+\fBUSE_EXPAND_HIDDEN\fR = \fI[space delimited list of variable names]\fR
+Names of \fBUSE_EXPAND\fR variables that should not be shown in the verbose merge
+list output of the \fBemerge\fR(1) command.
+.TP
\fBUSE_ORDER\fR = \fI"env:pkg:conf:auto:defaults"\fR
Determines precedence for incrementing the setting of the USE variable.
The above setting will cause the environment (env) to override per package (pkg)
you're doing. If you change this and something breaks, we will not help
you fix it.
.br
-Defaults to "env:pkg:conf:auto:defaults".
+Defaults to "env:pkg:conf:defaults".
.SH "REPORTING BUGS"
Please report bugs via http://bugs.gentoo.org/
Daniel Robbins <drobbins@gentoo.org>
Nicholas Jones <carpaski@gentoo.org>
Mike Frysinger <vapier@gentoo.org>
+Saleem Abdulrasool <compnerd@gentoo.org>
.fi
.SH "FILES"
.TP
packages
packages.build
package.provided
+package.use.force
+package.use.mask
parent
-use.defaults
+profile.bashrc
+use.force
use.mask
virtuals
.fi
.BR /etc/portage/
.nf
bashrc
+modules
package.mask
package.unmask
package.keywords
x11-base/xorg-x11-6.8
.fi
.TP
+.BR package.use.force
+Per\-package USE flag forcing.
+
+.I Note:
+In a cascading profile setup, you can remove USE flags in children
+profiles which were added by parent profiles by prefixing the flag with
+a '\-'.
+
+.I Format:
+.nf
+\- comments begin with #
+\- one DEPEND atom per line with space-delimited USE flags
+.fi
+
+.I Example:
+.nf
+# force docs for GTK 2.x
+=x11\-libs/gtk+\-2* doc
+# unforce mysql support for QT
+x11\-libs/qt \-mysql
+.fi
+.TP
+.BR package.use.mask
+Per\-package USE flag masks.
+
+.I Note:
+In a cascading profile setup, you can remove USE flags in children
+profiles which were added by parent profiles by prefixing the flag with
+a '\-'.
+
+.I Format:
+.nf
+\- comments begin with #
+\- one DEPEND atom per line with space-delimited USE flags
+.fi
+
+.I Example:
+.nf
+# mask docs for GTK 2.x
+=x11\-libs/gtk+\-2* doc
+# unmask mysql support for QT
+x11\-libs/qt \-mysql
+.fi
+.TP
.BR parent
This contains a path to the parent profile. It may be either relative or
absolute. The paths will be relative to the location of the profile. Most
commonly this file contains '..' to indicate the directory above. Utilized
only in cascading profiles.
.TP
-.BR use.defaults
-Here we DO NOT define the default USE flags, but the so\-called auto\-USE
-flags. This rather unknown portage feature activates a USE flag if a
-specific package is installed and the flag was not explicitly
-deactivated. This file contains the associations between USE flags and
-packages that trigger the auto\-USE feature.
+.BR profile.bashrc
+If needed, this file can be used to set up a special environment for ebuilds,
+different from the standard root environment. The syntax is the same as for
+any other bash script.
+.TP
+.BR use.force
+Some USE flags don't make sense to disable under certain conditions. Here we
+list forced flags.
-In other words, if we never put "sdl" or "\-sdl" into our USE, but we
-have media\-libs/libsdl emerged, then portage automagically sticks "sdl"
-into our USE for us.
+.I Note:
+In a cascading profile setup, you can remove USE flags in children
+profiles which were added by parent profiles by prefixing the flag with
+a '\-'.
.I Format:
.nf
\- comments begin with #
-\- one USE flag per line with a list of DEPEND atom bases
-.fi
-
-.I Example:
-.nf
-# media\-libs/libsdl will activate "sdl"
-sdl media\-libs/libsdl
-# activate tcltk only if we have both
-# dev\-lang/tcl and dev\-lang/tk
-tcltk dev\-lang/tcl dev\-lang/tk
+\- one USE flag per line
.fi
.TP
.BR use.mask
.RE
.TP
.BR /etc/portage/
+Any file in this directory that begins with "package." can be more than just a
+flat file. If it is a directory, then all the files in that directory will be
+summed together as if it were a single file.
+
+.I Example:
+.nf
+/etc/portage/package.keywords/kde
+/etc/portage/package.keywords/common
+/etc/portage/package.keywords/e17
+.fi
.RS
.TP
.BR bashrc
different from the standard root environment. The syntax is the same as for
any other bash script.
.TP
+.BR modules
+This file can be used to override the metadata cache implementation. In
+practice, portdbapi.auxdbmodule is the only variable that the user will want to
+override.
+
+.I Example:
+.nf
+portdbapi.auxdbmodule = cache.metadata_overlay.database
+.fi
+
+The metadata_overlay cache module makes it possible to disable
+FEATURES="metadata-transfer" in \fBmake.conf\fR(5). When the user initially
+enables metadata_overlay in /etc/portage/modules, all of the cache files
+contained in /var/cache/edb/dep/${PORTDIR} must be manually removed in order
+to avoid unecessary cache regeneration. In addition, users of the
+metadata_overlay module must never modify eclasses in ${PORTDIR} because
+portage will not be able to detect that cache regeneration is necessary. If
+the user would like to modify eclasses, it is safe to use metadata_overlay
+together with PORTDIR_OVERLAY in \fBmake.conf\fR.
+.TP
.BR package.mask
-A list of DEPEND atoms to mask. Useful if specific versions of packages do
+A list of package atoms to mask. Useful if specific versions of packages do
not work well for you. For example, you swear by the Nvidia drivers, but only
versions earlier than 1.0.4496. No problem!
mirrors file at /usr/portage/profiles/thirdpartymirrors. You may also set a
special mirror type called "local". This list of mirrors will be checked
before GENTOO_MIRRORS and will be used even if the package has
-RESTRICT="mirror".
+RESTRICT="mirror" or RESTRICT="fetch".
.I Format:
.nf
.B LICENSE.syntax
Syntax error in LICENSE (usually an extra/missing space/parenthesis)
.TP
+.B LIVEVCS.stable
+Ebuild is a live ebuild (cvs, git, darcs, svn, etc) checkout with stable keywords.
+.TP
.B PDEPEND.bad
User-visible ebuilds with bad PDEPEND settings (matched against *visible* ebuilds)
.TP
projects / portage.git / commitdiff