Add FEATURES=config-protect-if-modified support.

[portage.git] / man / make.conf.5

.TH "MAKE.CONF" "5" "August 2011" "Portage VERSION" "Portage"
.SH "NAME"
make.conf \- custom settings for Portage
.SH "SYNOPSIS"
\fB/etc/make.conf\fR and \fB/etc/portage/make.conf\fR
.SH "DESCRIPTION"
This file contains various variables that are used by Portage.
Portage will check the currently\-defined environment variables
first for any settings.  If no environment settings are found,
Portage then checks the make.conf files. Both /etc/make.conf and
/etc/portage/make.conf are checked (if present), and settings from
/etc/portage/make.conf will override settings from /etc/make.conf.
If no setting is found in the make.conf files, Portage checks
make.globals. If no
setting is found there, the profile's default setting is grabbed
from /etc/make.profile/make.defaults. Please note that all user
settings should be made in the environment or in the make.conf
files, which are intended to be customized by the user.
.br
Exceptions are incremental variables such as USE, CONFIG_PROTECT*,
and ACCEPT_KEYWORDS.  Incremental variables are propagated down from
make.defaults to make.globals to make.conf to the environment
settings.  Clearing these variables requires a clear\-all as in:
export USE="\-*"
.br
In order to create per\-package environment settings, refer to
\fBpackage.env\fR in \fBportage\fR(5).
.SH "VARIABLES"
.TP
\fBACCEPT_CHOSTS\fR = \fI[space delimited list of CHOST values]\fR
Specifies acceptable \fBCHOST\fR values. Regular
expression syntax is supported, so it is necessary to escape
\fBCHOST\fR characters if they have special meaning in regular expressions.
.br
Defaults to the value of $CHOST.
.TP
\fBACCEPT_KEYWORDS\fR = \fI[space delimited list of KEYWORDS]\fR
Enable testing of ebuilds that have not yet been deemed 'stable'.  Users
of the 'x86' architecture would set this to '~x86' while ppc users would
set this to '~ppc'.  This is an incremental variable.  Only define a 
~arch.
.br
Defaults to the value of $ARCH.
.TP
\fBACCEPT_LICENSE\fR = \fI[space delimited list of licenses or groups]\fR
This variable is used to mask packages based on licensing restrictions. It
may contain both license and group names, where group names are prefixed
with the '@' symbol. License groups are defined in the \fIlicense_groups\fR
file (see \fBportage\fR(5)). In addition to license and group names, the
\fI*\fR and \fI-*\fR wildcard tokens are also supported. Refer to GLEP 23
for further information:
\fIhttp://www.gentoo.org/proj/en/glep/glep-0023.html\fR.
.br
Defaults to the value of * -@EULA.
.br
.I Examples:
.nf
# Accept any license
ACCEPT_LICENSE="*"
# Accept any license except the "public-domain" license
ACCEPT_LICENSE="* -public-domain"
# Only accept licenses in the FSF-APPROVED license group
ACCEPT_LICENSE="-* @FSF-APPROVED"
.fi
.TP
\fBACCEPT_PROPERTIES\fR = \fI[space delimited list of properties]\fR
This variable is used to mask packages based on PROPERTIES restrictions.
In addition to property names, the \fI*\fR and \fI-*\fR wildcard tokens are
also supported. This variable can be temporarily overridden using the
\fB\-\-accept\-properties\fR option of \fBemerge\fR(1).
See \fBebuild\fR(5) for more information about PROPERTIES. 
.br
Defaults to the value of *.
.br
.I Examples:
.nf
# Accept any properties
ACCEPT_PROPERTIES="*"
# Accept any properties except the "interactive" property
ACCEPT_PROPERTIES="* -interactive"
.fi
.TP
.B CBUILD
This variable is passed by the \fIebuild scripts\fR to the \fIconfigure\fR
as \fI\-\-build=${CBUILD}\fR only if it is defined.  Do not set this yourself
unless you know what you are doing.
.TP
\fBCCACHE_DIR\fR = \fI[path]\fR
Defines the location of the ccache working directory.  See the \fBccache\fR(1)
man page for more information.
.br
Defaults to /var/tmp/ccache
.TP
\fBCCACHE_SIZE\fR = \fI"size"\fR
This controls the space use limitations for ccache.  The default is 2 gigabytes 
('2G').  Sizes are specified with 'G', 'M', or 'K'.
.TP
.B CFLAGS CXXFLAGS
Use these variables to set the desired optimization/CPU instruction settings
for applications that you compile.  These two variables are passed to the C
and C++ compilers, respectively. (CXX is used to refer to the C++ compiler
within many buildsystems.) Nearly all ebuild files will take advantage
of your custom settings, resulting in a Gentoo Linux that is fully customized
to your specifications.  Please use sane settings as some packages will fail to
compile/run if the optimizations are too extreme.

For more information, see the \fIInvoking GCC\fR section of the gcc manual:
.br
http://gcc.gnu.org/onlinedocs/
.TP
.B CHOST
This variable is passed by the \fIebuild scripts\fR to the \fIconfigure\fR
step as \fI\-\-host=${CHOST}\fR.  This way you can force the build\-host.

For more information:
.br
http://gcc.gnu.org/onlinedocs/gcc\-4.1.1/gcc/Submodel\-Options.html
.br
http://gcc.gnu.org/onlinedocs/gcc\-3.3/gcc/Submodel\-Options.html
.br
http://gcc.gnu.org/onlinedocs/gcc\-3.2/gcc/Submodel\-Options.html
.br
http://gcc.gnu.org/onlinedocs/gcc\-2.95.3/gcc_2.html
.TP
\fBCLEAN_DELAY\fR = \fIinteger\fR
Determines how long the countdown delay will be after running
`emerge --unmerge`.
.br
Defaults to 5 seconds.
.TP
\fBCOLLISION_IGNORE\fR = \fI[space delimited list of files and/or directories]\fR
This variable allows the user to disable \fIcollision\-protect\fR and
\fIprotect\-owned\fR for specific files and/or directories.
.br
Defaults to /lib/modules.
.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. See the \fBCONFIGURATION FILES\fR section
of \fBemerge\fR(1) for more information.
.TP
\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. See the \fBCONFIGURATION FILES\fR section
of \fBemerge\fR(1) for more information.
.TP
.B CTARGET
This variable is passed by the \fIebuild scripts\fR to the \fIconfigure\fR
as \fI\-\-target=${CTARGET}\fR only if it is defined.
.TP
\fBDISTDIR\fR = \fI[path]\fR
Defines the location of your local source file repository. After packages
are built, it is safe to remove any and all files from this directory since
they will be automatically fetched on demand for a given build. If you would
like to selectively prune obsolete files from this directory, see
\fBeclean\fR(1) from the gentoolkit package.

Use the \fBPORTAGE_RO_DISTDIRS\fR variable to specify one or
more read-only directories containing distfiles.

Note
that locations under /usr/portage are not necessarily safe for data storage.
See the \fBPORTDIR\fR documentation for more information.
.br
Defaults to /usr/portage/distfiles.
.TP
.B DOC_SYMLINKS_DIR
If this variable contains a directory then symlinks to html documentation will
be installed into it.
.TP
.B EBEEP_IGNORE
Defines whether or not to ignore audible beeps when displaying important
informational messages.  This variable is unset by default.
.TP
.B EMERGE_DEFAULT_OPTS
Options to append to the end of the \fBemerge\fR(1) command line on every invocation.
These options will not be appended to the command line if \-\-ignore\-default\-opts
is specified.
.TP
.B EMERGE_LOG_DIR
Controls the location of emerge.log and emerge-fetch.log.
.br
Defaults to /var/log.
.TP
\fBEMERGE_WARNING_DELAY\fR = \fIinteger\fR
Determines how long the countdown delay will be after running
`emerge --unmerge` for a system package.
.br
Defaults to 10 seconds.
.TP
.B EPAUSE_IGNORE
Defines whether or not to ignore short pauses that occur when displaying
important informational messages.  This variable is unset by default.
If it is set to any value pauses are ignored.
.TP
\fBEXTRA_ECONF\fR = \fI[configure options string]\fR
Contains additional options that \fBeconf\fR will append to configure
script arguments (see \fBebuild\fR(5)).
.TP
\fBFEATURES\fR = \fI"sandbox"\fR
Defines actions portage takes by default. This is an incremental variable.
Most of these settings are for developer use, but some are available to
non-developers as well. The \fBsandbox\fR feature is very important and
should not be disabled by default.
.RS
.TP
.B assume\-digests
When commiting work to cvs with \fBrepoman\fR(1), assume that all existing 
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). Existing digests for files that do not exist
in ${DISTDIR} will be automatically assumed even when \fIassume\-digests\fR is
not enabled. If a file exists in ${DISTDIR} but its size does not match the
existing digest, the digest will be regenerated regardless of whether or
not \fIassume\-digests\fR is enabled. The \fBebuild\fR(1) \fBdigest\fR command
has a \fB\-\-force\fR option that can be used to force regeneration of digests.
.TP
.B binpkg\-logs
Keep logs from successful binary package merges. This is relevant only when
\fBPORT_LOGDIR\fR is set.
.TP
.B buildpkg
Binary packages will be created for all packages that are merged. Also see
\fBquickpkg\fR(1) and \fBemerge\fR(1) \fB\-\-buildpkg\fR and
\fB\-\-buildpkgonly\fR options.
.TP
.B buildsyspkg
Build binary packages for just packages in the system set.
.TP
.B candy
Enable a special progress indicator when \fBemerge\fR(1) is calculating
dependencies.
.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 
${PORTAGE_TMPDIR}/ccache.

\fBWarning\fR: This feature is known to cause numerous compilation failures.
Sometimes ccache will retain stale code objects or corrupted files, which can
lead to packages that cannot be emerged. If this happens (if you receive errors
like "File not recognized: File truncated"), try recompiling the application
with ccache disabled before reporting a bug. Unless you are doing development
work, do not enable ccache.
.TP
.B clean\-logs
Enable automatic execution of the command specified by the
PORT_LOGDIR_CLEAN variable. The default PORT_LOGDIR_CLEAN setting will
remove all files from PORT_LOGDIR that were last modified at least 7
days ago.
.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. Also see the related \fIprotect\-owned\fR feature.
.TP
.B compress\-build\-logs
The causes all build logs to be compressed while they are being written.
Log file names have an extension that is appropriate for the compression
type. Currently, only \fBgzip\fR(1) compression is supported, so build
logs will have a '.gz' extension when this feature is enabled.
.TP
.B config\-protect\-if\-modified
This causes the \fBCONFIG_PROTECT\fR behavior to be skipped for files
that have not been modified since they were installed.
.TP
.B digest
Autogenerate digests for packages when running the
\fBemerge\fR(1), \fBebuild\fR(1), or \fBrepoman\fR(1) commands. 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.
.TP
.B distcc\-pump
Enable portage support for the distcc package with pump mode.
.TP
.B distlocks
Portage uses lockfiles to ensure competing instances don't clobber
each other's files. This feature is enabled by default but may cause
heartache on less intelligent remote filesystems like NFSv2 and some
strangely configured Samba server (oplocks off, NFS re\-export). A tool
/usr/lib/portage/bin/clean_locks exists to help handle lock issues
when a problem arises (normally due to a crash or disconnect).
.TP
.B ebuild\-locks
Use locks to ensure that unsandboxed ebuild phases never execute
concurrently. Also see \fIparallel\-install\fR.
.TP
.B fakeroot
Enable fakeroot for the install and package phases when a non-root user runs
the \fBebuild\fR(1) command.
.TP
.B fail\-clean
Clean up temporary files after a build failure. This is particularly useful
if you have \fBPORTAGE_TMPDIR\fR on tmpfs. If this feature is enabled, you
probably also want to enable \fBPORT_LOGDIR\fR in order to save the build log.
Both the \fBebuild\fR(1) command and the \fInoclean\fR feature cause the
\fIfail\-clean\fR feature to be automatically disabled.
.TP
.B getbinpkg
Force emerges to always try to fetch files from the \fIPORTAGE_BINHOST\fR.  See 
\fBmake.conf\fR(5) for more information.
.TP
.B installsources
Install source code into /usr/src/debug/${CATEGORY}/${PF} (also see
\fBsplitdebug\fR). This feature works only if debugedit is installed and CFLAGS
is set to include debug information (such as with the \-ggdb flag).
.TP
.B keeptemp
Do not delete the ${T} directory after the merge process.
.TP
.B keepwork
Do not delete the ${WORKDIR} directory after the merge process. ${WORKDIR} can
then be reused since this feature disables most of the clean phase that runs
prior to each build. Due to lack of proper cleanup, this feature can
interfere with normal emerge operation and therefore it should not be left
enabled for more than a short period of time.
.TP
.B fixlafiles
Modifies .la files to not include other .la files and some other
fixes (order of flags, duplicated entries, ...)
.TP
.B force\-mirror
Only fetch files from configured mirrors, ignoring \fBSRC_URI\fR,
except when \fImirror\fR is in the \fBebuild\fR(5) \fBRESTRICT\fR variable.
.TP
.B force\-prefix
Enable prefix support for all ebuilds, regardless of EAPI, since older EAPIs
would otherwise be useless with prefix configurations. This brings
compatibility with the prefix branch of portage, which also supports EPREFIX
for all EAPIs (for obvious reasons).
.TP
.B lmirror
When \fImirror\fR is enabled in \fBFEATURES\fR, fetch files even
when \fImirror\fR is also in the \fBebuild\fR(5) \fBRESTRICT\fR variable.
Do \fBNOT\fR use \fIlmirror\fR for clients that need to override \fBRESTRICT\fR
when fetching from a local mirror, but instead use a "local" mirror setting
in \fI/etc/portage/mirrors\fR, as described in \fBportage\fR(5).
.TP
.B metadata\-transfer
Automatically perform a metadata transfer when `emerge \-\-sync` is run.
In versions of portage >=2.1.5, this feature is disabled by
default. When metadata\-transfer is disabled, metadata cache from the
${PORTDIR}/metadata/cache/ directory will be used directly (if available)
and eclasses in ${PORTDIR}/eclass/ must not be modified except by
`emerge \-\-sync` operations since the cache validation mechanism
will not recognize eclass modifications. Normally, this issue only
pertains to users of the rsync tree since the cvs tree does not contain
a metadata/cache/ directory. Users of the rsync tree who want to modify
eclasses should use \fBPORTDIR_OVERLAY\fR in order for the cache
validation mechanism to work correctly.
.TP
.B mirror
Fetch everything in \fBSRC_URI\fR regardless of \fBUSE\fR settings,
except do not fetch anything when \fImirror\fR is in \fBRESTRICT\fR.
.TP
.B multilib\-strict
Many Makefiles assume that their libraries should go to /usr/lib, or
$(prefix)/lib. This assumption can cause a serious mess if /usr/lib
isn't a symlink to /usr/lib64. To find the bad packages, we have a
portage feature called \fImultilib\-strict\fR. It will prevent emerge
from putting 64bit libraries into anything other than (/usr)/lib64.
.TP
.B news
Enable GLEP 42 news support. See
\fIhttp://www.gentoo.org/proj/en/glep/glep-0042.html\fR.
.TP
.B noauto
When utilizing \fBebuild\fR(1), only run the function requested.
.TP
.B noclean
Do not delete the the source and temporary files after the merge process.
.TP
.B nodoc
Do not install doc files (/usr/share/doc).
.TP
.B noinfo
Do not install info pages.
.TP
.B noman
Do not install manpages.
.TP
.B nostrip
Prevents the stripping of binaries that are merged to the live filesystem.
.TP
.B notitles
Disables xterm titlebar updates (which contains status info).
.TP
.B parallel\-fetch
Fetch in the background while compiling. Run
`tail \-f /var/log/emerge\-fetch.log` in a
terminal to view parallel-fetch progress.
.TP
.B parallel\-install
Use finer\-grained locks when installing packages, allowing for greater
parallelization. For additional parallelization, disable
\fIebuild\-locks\fR.
.TP
.B parse\-eapi\-ebuild\-head
Parse \fBEAPI\fR from the head of the ebuild (first 30 lines). This feature
is only intended for experimental purposes and should not be enabled under
normal circumstances.
.TP
.B prelink\-checksums
If \fBprelink\fR(8) is installed then use it to undo any prelinks on files
before computing checksums for merge and unmerge. This feature is
useful only if \fBprelink\fR(8) is installed and accurate checksums (despite
prelinking) are needed for some reason such as for checking the integrity of
installed files or because the \fIunmerge\-orphans\fR feature is disabled.

Note that normal emerging of packages from source computes the
checksums before things will be prelinked, so in such cases, this
feature isn't required either. Undoing prelinking while merging is
only required when using tools like \fBquickpkg\fR(1) which can cause
already prelinked files to be merged.
.TP
.B preserve\-libs
Preserve libraries when the sonames change during upgrade or downgrade.
Libraries are preserved only if consumers of those libraries are detected.
.TP
.B protect\-owned
This is identical to the \fIcollision\-protect\fR feature except that files
may be overwritten if they are not explicitly listed in the contents of a
currently installed package. This is particularly useful on systems that
have lots of orphan files that have been left behind by older versions
of portage that did not support the \fIunmerge\-orphans\fR feature. Like
\fIcollision\-protect\fR, the \fICOLLISION_IGNORE\fR variable can be used to
selectively disable this feature. It is recommended to leave either
\fIprotect\-owned\fR or \fIcollision\-protect\fR enabled at all times,
since otherwise file collisions between packages may result in files being
overwritten or uninstalled at inappropriate times.
If \fIcollision\-protect\fR is enabled then it takes precedence over
\fIprotect\-owned\fR. 
.TP
.B python\-trace
Output a verbose trace of python execution to stderr when a command's 
\-\-debug option is enabled.
.TP
.B sandbox
Enable sandbox\-ing when running \fBemerge\fR(1) and \fBebuild\fR(1).
.TP
.B sesandbox
Enable SELinux sandbox\-ing.  Do not toggle this \fBFEATURE\fR yourself.
.TP
.B sfperms
Stands for Smart Filesystem Permissions.  Before merging packages to the 
live filesystem, automatically search for and set permissions on setuid 
and setgid files.  Files that are setuid have the group and other read 
bits removed while files that are setgid have the other read bit removed.  
See also \fIsuidctl\fR below.
.TP
.B sign
When commiting work to cvs with \fBrepoman\fR(1), sign the Manifest with 
a GPG key.  Read about the \fIPORTAGE_GPG_KEY\fR variable in \fBmake.conf\fR(5).
.TP
.B skiprocheck
Skip write access checks on \fBDISTDIR\fR when fetching files. This is
useful when \fBFETCHCOMMAND\fR and \fBRESUMECOMMAND\fR are used to
forward fetch requests to a server that exposes \fBDISTDIR\fR as
a read-only NFS share. A read-only \fBDISTDIR\fR is not compatible with the
\fIdistlocks\fR, so it is recommended to also add "-distlocks" to
\fBFEATURES\fR in order to avoid warning messages that are triggered by this
incompatibility.
.TP
.B split\-elog
Store logs created by \fBPORTAGE_ELOG_SYSTEM="save"\fR in category
subdirectories of \fBPORT_LOGDIR/elog\fR, instead of using
\fBPORT_LOGDIR/elog\fR directly.
.TP 
.B split\-log
Store build logs in category subdirectories of \fBPORT_LOGDIR/build\fR,
instead of using \fBPORT_LOGDIR\fR directly.
.TP
.B splitdebug
Prior to stripping ELF etdyn and etexec files, the debugging info is 
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 digests for ebuilds).
.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.
.TP
.B test
Run package\-specific tests during each merge to help make sure 
the package compiled properly.  See \fItest\fR in \fBebuild\fR(1) 
and \fIsrc_test()\fR in \fBebuild\fR(5). This feature implies the "test"
\fBUSE\fR flag.
.TP
.B test\-fail\-continue
If "test" is enabled \fBFEATURES\fR and the test phase of an ebuild fails,
continue to execute the remaining phases as if the failure had not occurred.
Note that the test phase for a specific package may be disabled by masking
the "test" \fBUSE\fR flag in \fBpackage.use.mask\fR (see \fBportage\fR(5)).
.TP
.B unmerge\-logs
Keep logs from successful unmerge phases. This is relevant only when
\fBPORT_LOGDIR\fR is set.
.TP
.B unmerge\-orphans
If a file is not claimed by another package in the same slot and it is not
protected by \fICONFIG_PROTECT\fR, unmerge it even if the modification time or
checksum differs from the file that was originally installed.
.TP
.B unknown\-features\-filter
Filter out any unknown values that the FEATURES variable contains.
.TP
.B unknown\-features\-warn
Warn if FEATURES contains one or more unknown values.
.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 privileges and compile packages as 
portage:portage without a sandbox (unless \fIusersandbox\fR is also used).
.TP
.B usersandbox
Enable the sandbox in the compile phase, when running without root privs (\fIuserpriv\fR).
.TP
.B usersync
Drop privileges to the owner of \fBPORTDIR\fR for \fBemerge(1) --sync\fR
operations.
.TP
.B webrsync-gpg
Enable GPG verification when using \fIemerge\-webrsync\fR.
.TP
.B xattr
Preserve extended attributes (filesystem-stored metadata) when installing
files (see \fBattr\fR(1)).
.RE
.TP
.B FETCHCOMMAND
This variable contains the command used for fetching package sources from
the internet.  It must contain the full path to the executable as well as the
place\-holders \\${DISTDIR}, \\${FILE} and \\${URI}.  The command should be
written to place the fetched file at \\${DISTDIR}/\\${FILE}.
Also see \fBRESUMECOMMAND\fR.
.TP
.B FFLAGS FCFLAGS
Use these variables to set the desired optimization/CPU instruction settings
for applications that you compile with a FORTRAN compiler. FFLAGS is usually
passed to the FORTRAN 77 compiler, and FCFLAGS to any FORTRAN compiler in
more modern build systems.

For more information, see the \fIInvoking GCC\fR section of the gcc manual:
.br
http://gcc.gnu.org/onlinedocs/
.TP
\fBGENTOO_MIRRORS\fR = \fI[URIs]\fR
Insert your space\-separated list of local mirrors here.  These
locations are used to download files before the ones listed in
the \fIebuild scripts\fR. Merging 'mirrorselect' can help.  Entries in this
variable that have no protocol and simply start with a '/' path separator may
be used to specify mounted filesystem mirrors.
.TP
\fBhttp_proxy ftp_proxy\fR = \fI[protocol://host:port]\fR
These vars are used if the sources must be downloaded from the
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. The \fBINSTALL_MASK\fR is processed just before a package is merged.
Also supported is a \fBPKG_INSTALL_MASK\fR variable that behaves exactly like
\fBINSTALL_MASK\fR except that it is processed just before creation of a binary
package.
.TP
.B LDFLAGS
A list of flags to pass to the compiler when the linker will be called. See
\fBld\fR(1) for linker flags, but don't forget that these flags will be passed
directly to the compiler. Thus, you must use '-Wl' to escape the flags
which only the linker understands (see \fBgcc\fR(1)).

\fB***warning***\fR
.br
Setting this and other *FLAGS variables arbitrarily may cause compile or
runtime failures. Bug reports submitted when nonstandard values are
enabled for these flags may be closed as INVALID.
.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 
enhanced build performance with many packages. Suggested settings are
between \fICPUs+1\fR and \fI2*CPUs+1\fR. In order to avoid
excess load, the \fB\-\-load\-average\fR option is recommended.
For more information, see \fBmake\fR(1). Also see \fBemerge\fR(1) for
information about analogous \fB\-\-jobs\fR and \fB\-\-load\-average\fR options.
.TP
\fBNOCOLOR\fR = \fI["true" | "false"]\fR
Defines if color should be disabled by default.
.br
Defaults to false.
.TP
\fBPKGDIR\fR = \fI[path]\fR
Defines the location where created .tbz2 binary packages will be
stored when the \fBemerge\fR(1) \fB\-\-buildpkg\fR option is enabled.
By default, a given package is stored in a subdirectory corresponding
to it's category. However, for backward compatibility with the layout
used by older versions of portage, if the \fI${PKGDIR}/All\fR directory
exists then all packages will be stored inside of it and symlinks to
the packages will be created in the category subdirectories. Note
that locations under /usr/portage are not necessarily safe for data storage.
See the \fBPORTDIR\fR documentation for more information.
.br
Defaults to /usr/portage/packages.
.TP
.B PORT_LOGDIR
This variable defines the directory in which per\-ebuild logs are kept.
Logs are created only when this is set. They are stored as
${CATEGORY}:${PF}:YYYYMMDD\-HHMMSS.log in the directory specified. If the
directory does not exist, it will be created automatically and group permissions
will be applied to it.  If the directory already exists, portage will not
modify it's permissions.
.TP
.B PORT_LOGDIR_CLEAN
This variable should contain a command for portage to call in order
to clean PORT_LOGDIR. The command string should contain a
\\${PORT_LOGDIR} place\-holder that will be substituted
with the value of that variable. This variable will have no effect
unless \fBclean\-logs\fR is enabled in \fBFEATURES\fR.
.TP
\fBPORTAGE_BINHOST\fR = \fI[space delimited URI list]\fR
This is a list of hosts from which portage will grab prebuilt\-binary packages.
Each entry in the list must specify the full address of a directory
serving tbz2's for your system. This is only used when running with
the get binary pkg options are given to \fBemerge\fR.  Review \fBemerge\fR(1) 
for more information.  For versions of portage less that 2.1.6, this variable
should point to the 'All' directory on the host that creates the binary
packages and not to the root of the \fBPKGDIR\fR.  Starting with portage 2.1.6,
it should point to a directory containing a 'Packages' index file.  If
${PORTAGE_BINHOST}/Packages does not exist then portage will attempt to use
the older protocol.
.TP
\fBPORTAGE_BINHOST_HEADER_URI\fR = \fI"ftp://login:pass@grp.mirror.site/pub/grp/i686/athlon\-xp/"\fR
This variable only makes sense on a system that will serve as a binhost and
build packages for clients.  It defines the URI header field for the package
index file which is located at ${PKGDIR}/Packages. Clients that have
\fBPORTAGE_BINHOST\fR properly configured will be able to fetch the index and
use the URI header field as a base URI for fetching binary packages. If the URI
header field is not defined then the client will use it's ${PORTAGE_BINHOST}
setting as the base URI.
.TP
.B PORTAGE_BINPKG_TAR_OPTS
This variable contains options to be passed to the tar command for creation
of binary packages.
.TP
\fBPORTAGE_BUNZIP2_COMMAND\fR = \fI[bunzip2 command string]\fR
This variable should contain a command that is suitable for portage to call
for bunzip2 extraction operations.
.TP
\fBPORTAGE_BZIP2_COMMAND\fR = \fI[bzip2 command string]\fR
This variable should contain a command that is suitable for portage to call
for bzip2 compression operations. \fBPORTAGE_BZIP2_COMMAND\fR will also be
called for extraction operation, with -d appended, unless the
\fBPORTAGE_BUNZIP2_COMMAND\fR variable is set.
.TP
\fBPORTAGE_COMPRESS\fR = \fI"bzip2"\fR
This variable contains the command used to compress documentation during the
install phase.
.TP
\fBPORTAGE_COMPRESS_FLAGS\fR = \fI"\-9"\fR
This variable contains flags for the \fBPORTAGE_COMPRESS\fR command.
.TP
.TP
\fBPORTAGE_COMPRESS_EXCLUDE_SUFFIXES\fR = \fI"gif htm[l]? jp[e]?g pdf png"\fR
This variable contains a space delimited list of file suffixes for which
matching files are excluded when the \fBPORTAGE_COMPRESS\fR command is
called. Regular expressions are supported and the match is performed only
against the portion of the file name which follows the last period character.
.TP
.B PORTAGE_ELOG_CLASSES
.TP
.B PORTAGE_ELOG_SYSTEM
.TP
.B PORTAGE_ELOG_COMMAND
.TP
.B PORTAGE_ELOG_MAILURI
.TP
.B PORTAGE_ELOG_MAILFROM
.TP
.B PORTAGE_ELOG_MAILSUBJECT
Please see /usr/share/portage/config/make.conf.example for elog documentation.
.TP
\fBPORTAGE_FETCH_CHECKSUM_TRY_MIRRORS\fR = \fI5\fR
Number of mirrors to try when a downloaded file has an incorrect checksum.
.TP
\fBPORTAGE_FETCH_RESUME_MIN_SIZE\fR = \fI350K\fR
Minimum size of existing file for \fBRESUMECOMMAND\fR to be called. Files
smaller than this size will be removed and \fBFETCHCOMMAND\fR will be called
to download the file from the beginning. This is useful for helping to ensure
that small garbage files such as html 404 pages are properly discarded. The
variable should contain an integer number of bytes and may have a suffix such
as K, M, or G.
.TP
.B PORTAGE_GPG_DIR
The \fBgpg\fR(1) home directory that is used by \fBrepoman\fR(1)
when \fBsign\fR is in \fBFEATURES\fR.
.br
Defaults to $HOME/.gnupg.
.TP
.B PORTAGE_GPG_KEY
The \fBgpg\fR(1) key used by \fBrepoman\fR(1) to sign manifests
when \fBsign\fR is in \fBFEATURES\fR.
.TP
.B PORTAGE_GPG_SIGNING_COMMAND
The command used by \fBrepoman\fR(1) to sign manifests when \fBsign\fR is
in \fBFEATURES\fR.
.TP
\fBPORTAGE_IONICE_COMMAND\fR = \fI[ionice command string]\fR
This variable should contain a command for portage to call in order
to adjust the io priority of portage and it's subprocesses. The command
string should contain a \\${PID} place-holder that will be substituted
with an integer pid. For example, a value of "ionice \-c 3 \-p \\${PID}"
will set idle io priority. For more information about ionice, see
\fBionice\fR(1). This variable is unset by default.
.TP
\fBPORTAGE_NICENESS\fR = \fI[number]\fR
The value of this variable will be added to the current nice level that
emerge is running at.  In other words, this will not set the nice level,
it will increment it.  For more information about nice levels and what
are acceptable ranges, see \fBnice\fR(1).
.TP
\fBPORTAGE_RO_DISTDIRS\fR = \fI[space delimited list of directories]\fR
When a given file does not exist in \fBDISTDIR\fR, search for the file
in this list of directories. Search order is from left to right. Note
that the current implementation works by creating a symlink inside
\fBDISTDIR\fR, but that may change in the future.
.TP
\fBPORTAGE_RSYNC_INITIAL_TIMEOUT\fR = \fIinteger\fR
Used by \fBemerge \-\-sync\fR as a timeout for the initial connection to an
rsync server.
.br
Defaults to 15 seconds.
.TP
\fBPORTAGE_RSYNC_EXTRA_OPTS\fR = \fI[rsync options string]\fR
Additional rsync options to be used by \fBemerge \-\-sync\fR.
.br
Defaults to no value.
.TP
\fBPORTAGE_RSYNC_OPTS\fR = \fI[rsync options string]\fR
Default rsync options to be used by \fBemerge \-\-sync\fR. 
.br
\fBDon't change this unless you know exactly what you're doing!\fR
.br
Defaults to "\-\-recursive \-\-links \-\-safe\-links \-\-perms \-\-times
\-\-compress \-\-force \-\-whole\-file \-\-delete \-\-stats
\-\-timeout=180 \-\-exclude='/distfiles' \-\-exclude='/local'
\-\-exclude='/packages'"
.TP
\fBPORTAGE_RSYNC_RETRIES\fR = \fI[NUMBER]\fR
The number of times rsync should retry on failed connections before
giving up. If set to a negative number, then retry until all possible
addresses are exhausted.
.br
Defaults to -1.
.TP
\fBPORTAGE_SYNC_STALE\fR = \fI[NUMBER]\fR
Defines the number of days after the last `emerge \-\-sync` that a warning
message should be produced. A value of 0 will disable warnings.
.br
Defaults to 30.
.TP
\fBPORTAGE_TMPDIR\fR = \fI[path]\fR
Defines the location of the temporary build directories.
.br
Defaults to /var/tmp.
.TP
\fBPORTAGE_WORKDIR_MODE\fR = \fI"0700"\fR
This variable controls permissions for \fIWORKDIR\fR (see \fBebuild\fR(5)).
.TP
\fBPORTDIR\fR = \fI[path]\fR
Defines the location of the Portage tree. This is the repository for all
profile information as well as all ebuilds. If you change this, you must update
your /etc/make.profile symlink accordingly.
.br
Defaults to /usr/portage. 
.br
\fB***Warning***\fR
.br
Data stored inside \fBPORTDIR\fR is in peril of being overwritten or deleted by
the emerge \-\-sync command. The default value of
\fBPORTAGE_RSYNC_OPTS\fR will protect the default locations of
\fBDISTDIR\fR and \fBPKGDIR\fR, but users are warned that any other locations
inside \fBPORTDIR\fR are not necessarily safe for data storage.  You should not 
put other data (such as overlays) in your \fBPORTDIR\fB.  Portage will walk 
directory structures and may arbitrary add invalid categories as packages.
.TP
\fBPORTDIR_OVERLAY\fR = \fI"[path] [different\-path] [etc...]"\fR
Defines the directories in which user made ebuilds may be stored and not 
overwriten when `emerge \-\-sync` is run.  This is a space delimited list of 
directories.
.br
Defaults to no value.
.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
\fBQA_STRICT_FLAGS_IGNORED = \fI"set"\fR
Set this to cause portage to ignore any \fIQA_FLAGS_IGNORED\fR override
settings from ebuilds.  See also \fBebuild\fR(5).
.TP
\fBQA_STRICT_DT_HASH = \fI"set"\fR
Set this to cause portage to ignore any \fIQA_DT_HASH\fR override
settings from ebuilds. This variable is deprecated. Use
\fIQA_STRICT_FLAGS_IGNORED\fR instead.
.TP
\fBQA_STRICT_PRESTRIPPED = \fI"set"\fR
Set this to cause portage to ignore any \fIQA_PRESTRIPPED\fR override
settings from ebuilds.  See also \fBebuild\fR(5).
.TP
.B RESUMECOMMAND
This variable contains the command used for resuming package sources that
have been partially downloaded.  It should be defined using the same format
as \fBFETCHCOMMAND\fR, and must include any additional option(s) that may
be necessary in order to continue a partially downloaded file located at
\\${DISTDIR}/\\${FILE}.
.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.  Make sure you use an absolute path.
.br
Defaults to /.
.TP
\fBRPMDIR\fR = \fI[path]\fR
Defines the location where created RPM packages will be stored.
.br
Defaults to ${PORTDIR}/rpm.
.TP
\fBSYNC\fR = \fI[RSYNC]\fR
Insert your preferred rsync mirror here.  This rsync server
is used to sync the local portage tree when `emerge \-\-sync` is run.
.br
Defaults to rsync://rsync.gentoo.org/gentoo\-portage
.TP
\fBUSE\fR = \fI[space delimited list of USE items]\fR
This variable contains options that control the build behavior of several
packages.  More information in \fBebuild\fR(5).  Possible USE values
can be found in \fI/usr/portage/profiles/use.desc\fR.
.TP
\fBUSE_EXPAND\fR = \fI[space delimited list of variable names]\fR
Any variable listed here will be used to augment USE by inserting a new flag
for every value in that variable, so USE_EXPAND="FOO" and FOO="bar bla" results
in USE="foo_bar foo_bla".
.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:defaults:pkginternal:repo:env.d"\fR
Determines the precedence of layers in the incremental stacking of the USE
variable. Precedence decreases from left to right such that env overrides
pkg, pkg overrides conf, and so forth.

.B ***warning***
.br
Do not modify this value unless you're a developer and you know what
you're doing. If you change this and something breaks, we will not help
you fix it.
.br
.RS
.TP
.B env
USE from the current environment variables (USE and those listed in USE_EXPAND)
.TP
.B pkg
Per\-package USE from \fB/etc/portage/package.use\fR (see \fBportage\fR(5))
.TP
.B conf
USE from make.conf
.TP
.B defaults
USE from make.defaults and package.use in the profile
(e.g. /etc/portage/make.profile/package.use) (see \fBportage\fR(5))
.TP
.B pkginternal
USE from \fBebuild\fR(5) IUSE defaults
.TP
.B repo
USE from make.defaults and package.use in the repo's profiles/ top dir
(e.g. /usr/portage/profiles/package.use) (see \fBportage\fR(5))
.TP
.B env.d
USE from the environment variables, such as LINGUAS, defined by files in
\fI/etc/env.d/\fR
.RE

.SH "REPORTING BUGS"
Please report bugs via http://bugs.gentoo.org/
.SH "AUTHORS"
.nf
Daniel Robbins <drobbins@gentoo.org>
Nicholas Jones <carpaski@gentoo.org>
Mike Frysinger <vapier@gentoo.org>
Saleem Abdulrasool <compnerd@gentoo.org>
.fi
.SH "FILES"
.TP
\fB/etc/make.conf\fR and \fB/etc/portage/make.conf\fR
Contains variables for the build\-process and overwrites those in make.defaults.
.TP
.B /usr/share/portage/config/make.globals
Contains the default variables for the build\-process, you should edit \fI/etc/make.conf\fR instead.
.TP
.B /etc/portage/color.map
Contains variables customizing colors.
.TP
.B /usr/portage/profiles/use.desc
Contains a list of all global USE flags.
.TP
.B /usr/portage/profiles/use.local.desc
Contains a list of all local USE variables.
.SH "SEE ALSO"
.BR emerge (1),
.BR portage (5),
.BR ebuild (1),
.BR ebuild (5)
.TP
The \fI/usr/sbin/ebuild.sh\fR script. 
.TP
The helper apps in \fI/usr/lib/portage/bin\fR.