path: root/make.conf.txt

make.conf
*********

Available make.conf settings for portage

SYNOPSIS
========

/etc/make.conf

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 /etc/make.conf.  If no setting is found
in /etc/make.conf, Portage checks the profile's default setting
from /etc/make.profile/make.defaults. If no setting is found there, 
it finally checks /etc/make.globals. Please note that all user
settings should be made in the environment or in /etc/make.conf,
which is intended to be customized by the user.

VARIABLES
=========

ACCEPT_KEYWORDS
---------------

:suggest: |accept_keywords|
:valdesc: space delimited list of KEYWORDS

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.

CCACHE_DIR
----------

:suggest: ${PORTAGE_TMPDIR}/ccache
:valdesc: path

Defines the location of the ccache working directory. See the ccache(1) man 
page for more information.

CCACHE_SIZE
-----------

:valdesc: size

This controls the space use limitations for ccache.  The default is 2 gigabytes 
('2G').  Sizes are specified with 'G', 'M', or 'K'.

CFLAGS
------

:suggest: |cflags|
:valdesc: valid gcc flags, see gcc manual

Use these variables to set the desired optimization/CPU instruction settings
for applications that you compile.  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.

CXXFLAGS
--------

:suggest: ${CFLAGS}
:valdesc: valid gcc flags, see gcc manual

`CFLAGS`_

CHOST
-----

:suggest: |chost|

This variable is passed by the ebuild scripts to the configure step as 
--host=${CHOST}.  This way you can force the build-host.

CLEAN_DELAY
-----------

:default: 5
:valdesc: integer

Determines how long the countdown delay will be for unmerge operations (including 
autoclean).

COLLISION_IGNORE
----------------

:valdesc: space delimited list of files and/or directories

This variable allows the user to disable `collision-protect`_ for specific files 
and/or directories.

CONFIG_PROTECT
--------------

:default: /etc
:valdesc: space delimited list of files and/or directories

All  files  and/or  directories  that are defined here will have "config file 
protection" enabled for them (unless overridden by _`CONFIG_PROTECT_MASK`).

CONFIG_PROTECT_MASK
-------------------

:default: /etc/env.d
:valdesc: space delimited list of files and/or directories

All  files  and/or  directories  that are defined here will have "config file 
protection" disabled for them.

DISTCC_DIR
----------

:suggest: ${PORTAGE_TMPDIR}/.distcc
:valdesc: path

Defines the location of the distcc working directory. See the distcc(1) man 
page for more information.

DISTDIR
-------

:default: |portdir|/distfiles
:valdesc: path

Defines the location of your local source file repository.

EBEEP_IGNORE
------------

Defines whether or not to ignore audible beeps when displaying important 
informational messages.  This variable is unset by default.

EMERGE_DEFAULT_OPTS
-------------------

:valdesc: emerge options

Options  to append to the end of the emerge(1) command line on every invocation.
These options will not be appended to the command line if --ignore-default-opts 
is specified.

EPAUSE_IGNORE
-------------

Defines whether or not to ignore short pauses that occur when displaying 
important informational messages.  This variable is unset by default.

FEATURES
--------

:default: sandbox distlocks metadata-transfer
:suggest: userpriv usersandbox
:valdesc: space separated list of feature flags

Various settings affecting portage behavior. Don't disable the defaults without
a good reason. This is an incremental variable. It can take a combination of the
following flags:

_`assume-digests`
	When commiting work to cvs with repoman(1), assume that all existing SRC_URI 
	digests are correct.  This feature also affects digest generation via 
	ebuild(1) and emerge(1) (emerge generates digests only when the digest 
	feature is enabled).

_`buildpkg`
	Binary packages will be created for all packages that are merged.

_`buildsyspkg`
	Build binary packages for just packages in the system set.

_`ccache`
	Enable portage support for the ccache package.  If ${CCACHE_DIR} is not set 
	in the users environment, then  portage will default to ${PORTAGE_TMPDIR}/ccache 
	(with userpriv) and to /root/.ccache otherwise.

_`collision-protect`
	A QA-feature to ensure that a package doesn't overwrite files it doesn't own.
	The `COLLISION_IGNORE`_ variable can be used to selectively disable this feature.

_`digest`
	Autogenerate digests for packages when running the emerge(1) command. If
	the `assume-digests`_ feature is also enabled then existing SRC_URI digests
	will be reused whenever they are available.

_`distcc`
	Enable portage support for the distcc package.

_`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).

_`fixpackages`
	Updates dependencies in binary packages to match the current tree, for 
	example after package moves. This can take a ot of time if you have many
	binary packages in `PKGDIR`_.

_`getbinpkg`
	Force emerges to always try to fetch files from the `PORTAGE_BINHOST`_.

_`installsources`
	Install source code into /usr/src/debug/${CATEGORY}/${PF} (also see
	`splitdebug`_). This feature works only if debugedit is installed.

_`keeptemp`
	Do not delete the temporary ebuild directory ${T} after the merge process.

_`keepwork`
	Do not delete the build directory ${WORKDIR} after the merge process. This
	may occupy a lot of diskspace.

_`metadata-transfer`
	Automatically perform a metadata transfer when emerge --sync is run.

_`mirror`
	This will cause `FETCHCOMMAND`_ to always be run even if the file already 
	exists in `DISTDIR`_.

_`noauto`
	When utilizing ebuild(1), only run the requested function.

_`noclean`
	Do no delete the source and temporary files after the merge process.

_`nodoc`
	Do not install documentation files in /usr/share/doc.

_`noinfo`
	Do not install info pages.

_`noman`
	Do not install manpages.

_`nostrip`
	Prevents the stripping of binaries that are merged to the live filesystem.

_`notitles`
	Disables xterm titlebar updates (which contains status info).

_`parallel-fetch`
	Fetch in the background while compiling.

_`sandbox`
	Use sys-apps/sandbox when building packages to protect the live filesystem.

_`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 `suidctl`_ below.

_`sign`
	When commiting work to cvs with repoman(1), sign the Manifest with 
	a GPG key. Read about the `PORTAGE_GPG_KEY`_ variable.

_`splitdebug`
	Prior to stripping ELF etdyn and etexec files, the debugging info is 
	stored for later use by debuggers. This feature is disabled by
	`nostrip`_. For installation of source code, see `installsources`_.

_`strict`
	Have portage react strongly to conditions that have the potential to be 
	dangerous (like missing or incorrect Manifests entries).

_`stricter`
	Have portage react strongly to conditions that may conflict with system
	security provisions (for example textrels, executable stack). Read about
	the `QA_STRICT`_ variables below.

_`suidctl`
	Before merging packages to the live filesystem, automatically strip setuid 
	bits from any file that is not listed in /etc/portage/suidctl.conf.

_`test`
	Run package-specific tests during each merge to help make sure 
	the package compiled properly.  See *test* in ebuild(1) 
	and *src_test()* in ebuild(5).

_`userfetch`
	When portage is run as root, drop privileges to portage:portage during the
	fetching of package sources.

_`userpriv`
	Allow portage to drop root privileges and compile packages as 
	portage:portage without `sandbox`_ (unless `usersandbox`_ is also used).

_`usersandbox`
	Enable the sandbox in the compile phase, when running without root privs 
	(`userpriv`_).

FETCHCOMMAND
------------

:default: /usr/bin/wget -t 5 -T 60 --passive-ftp -P \${DISTDIR} \${URI}
:suggest: /usr/bin/wget -t 5 -T 60 --passive-ftp --limit-rate=200k \${URI} -P \${DISTDIR}

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} and \${URI}.

GENTOO_MIRRORS
--------------

:default: http://distfiles.gentoo.org http://distro.ibiblio.org/pub/linux/distributions/gentoo
:valdesc: space separated list of mirror locations

Insert your space-seperated list of local mirrors here. These locations are 
used to download files before the ones listed in the ebuild scripts. Merging 
'app-portage/mirrorselect' can help to select an appropriate mirror.

INSTALL_MASK
------------

:valdesc: space delimited list of file names

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.

MAKEOPTS
--------

:suggest: -j2
:valdesc: make options

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 CPUs+1 and 2*CPUs+1. For more information, see make(1).

NOCOLOR
-------

:default: false
:valdesc: true | false

Defines if color should be disabled (this is overridden by CLI options).

PKGDIR
------

:default: |portdir|/packages
:valdesc: path

Defines the location where created .tbz2 binary packages will be stored.

PORT_LOGDIR
-----------

:suggest: /var/log/portage
:valdesc: path

This variable defines the directory in which per-ebuild logs are kept.
Logs are created only when this is set and writable.

PORTAGE_BINHOST
---------------

:suggest: ftp://login:pass@grp.mirror.site/pub/grp/i686/athlon-xp
:valdesc: URI to a binary package server

This is the host from which portage will grab prebuilt-binary packages.
The list is a single entry specifying the full address of the directory 
serving the tbz2's for your system.  This is only used when running with 
the get binary pkg options are given to emerge.  Review emerge(1) 
for more information.  Note that it should point to the 'All' directory on 
the host that creates the binary packages and not to the root of the `PKGDIR`_.

PORTAGE_ELOG_CLASSES
--------------------

:default: log warn error
:valdesc: space separated list of logging levels

This variable defines which ebuild messages should be logged by the elog 
subsystem. Possible values are info, log, warn and error.

PORTAGE_ELOG_SYSTEM
-------------------

:suggest: save mail
:valdesc: space separated list of elog handlers

Selects which elog message handlers are invoked by portage to deliver messages
captured by elog. If no handler is specified logging is effectively disabled.
Default handlers (other packages may contain additional handlers) are:

save
	saves one logfile per package in ${PORT_LOGDIR}/elog, /var/log/portage/elog 
	if `PORT_LOGDIR`_ is unset

custom
	passes all messages to `PORTAGE_ELOG_COMMAND`_

syslog
	sends all messages to syslog

mail
	sends all messages to the address configured in `PORTAGE_ELOG_MAILURI`_

PORTAGE_ELOG_COMMAND
--------------------

:suggest: /path/to/logprocessor -p '\${PACKAGE}' -f '\${LOGFILE}'

Only used with the "custom" logging module. Specifies a command
to process log messages. Two variables are expanded:

${PACKAGE}
	expands to the cpv entry of the processed package (see PVR in ebuild(5))

${LOGFILE}
	absolute path to the logfile

Both variables have to be quoted with single quotes

PORTAGE_ELOG_MAILURI
--------------------

:default: root
:suggest: user@some.domain mail.some.domain

This variable holds all important settings for the mail module. In most cases 
listing the recipient address andthe receiving mailserver should be sufficient,
but you can also use advanced settings like authentication or TLS. The full 
syntax is:
``address [[user:passwd@]mailserver[:port]]``
where

address
	recipient address

user
	username for smtp auth (defaults to none)

passwd
	password for smtp auth (defaults to none)

mailserver
	SMTP server that should be used to deliver the mail (defaults to localhost).
	Alternatively this can also be a the path to a sendmail binary if you don't
	want to use SMTP (e.g. if you only need local delivery to a mbox).

port
	port to use on the given SMTP server (defaults to 25, values > 100000 
	indicate that starttls should be used on (port-100000))

PORTAGE_ELOG_MAILFROM
---------------------

:default: portage
:suggest: portage@some.domain
:valdesc: sender address

You can set the from-address of logmails with this variable, if unset mails 
are sent by "portage" (this default may fail in some environments).

PORTAGE_ELOG_MAILSUBJECT
------------------------

:default: [portage] ebuild log for \${PACKAGE} on \${HOST}
:suggest: package \${PACKAGE} merged on \${HOST} with notice
:valdesc: mail subject template

Template string to be used as subject for logmails. The following variables 
are exanded:

${PACKAGE}
	see description of `PORTAGE_ELOG_COMMAND`_

${HOST}
	FQDN of the host portage is running on

PORTAGE_GPG_KEY
---------------

:valdesc: GPG key id

This variable tells repoman which GPG key to use for signing Manifests.

PORTAGE_NICENESS
----------------

:suggest: 3
:valdesc: integer

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 nice(1).

PORTAGE_RSYNC_EXTRA_OPTS
------------------------

:suggest: --exclude=/etc/portage/rsync_exclude
:valdesc: rsync options

Additional rsync options to be used by emerge --sync.

PORTAGE_RSYNC_OPTS
------------------

:default: --recursive --links --safe-links --perms --times --compress --force --whole-file --delete --delete-after --stats --timeout=180 --exclude=/distfiles --exclude=/local --exclude=/packages
:valdesc: rsync options

Default rsync options to be used by emerge --sync. **Don't change this unless
you know exactly what you're doing!**

PORTAGE_RSYNC_RETRIES
---------------------

:default: 3
:valdesc: integer

The number of times rsync should retry on failed connections before giving up.

PORTAGE_TMPDIR
--------------

:default: /var/tmp
:valdesc: path

Defines the location of the temporary build directories.

PORTDIR
-------

:default: |portdir|
:valdesc: path

Defines the location of your Portage tree.

PORTDIR_OVERLAY
---------------

:suggest: |portdir|/local
:valdesc: space separated list of overlay paths

Defines the directories in which user made ebuilds are be stored.

RESUMECOMMAND
-------------

:default: /usr/bin/wget -c -t 5 -T 60 --passive-ftp -P \${DISTDIR} \${URI}
:suggest: /usr/bin/wget -c -t 5 -T 60 --passive-ftp --limit-rate=200k \${URI} -P \${DISTDIR}

This variable contains the command used for resuming package sources that
have been partially downloaded. It should be defined using the same format
as `FETCHCOMMAND`_.

.. _QA_STRICT:

QA_STRICT_EXECSTACK
-------------------

:suggest: set

Set this to instruct portage to ignore any QA_EXECSTACK override settings from
ebuilds. See also ebuild(5).

QA_STRICT_WX_LOAD
-----------------

:suggest: set

Set this to instruct portage to ignore any QA_WX_LOAD override settings from
ebuilds. See also ebuild(5).

QA_STRICT_TEXTRELS
------------------

:suggest: set

Set this to instruct portage to ignore any QA_TEXTRELS override settings from
ebuilds. See also ebuild(5).

ROOT
----

:default: /
:valdesc: path

Use this variable to specify the target root filesystem to be used for merging 
packages or ebuilds. All RDEPEND and PDEPEND will be installed 
into ROOT while all DEPEND will be still be installed into /.  
Typically, you should set this setting in the environment rather than in 
/etc/make.conf itself. It's commonly used for creating new build 
images. Make sure you use an absolute path.

RPMDIR
------

:default: |portdir|/rpm
:valdesc: path

Defines the location where created RPM packages will be stored. Note that RPM 
support in portage is experimental at best.

SYNC
----

:default: rsync://rsync.gentoo.org/gentoo-portage
:valdesc: URI to a portage tree server (rsync or cvs)

Insert your preferred rsync mirror here.  This rsync server is used to sync 
the local portage tree when emerge --sync is run. Only one server can be 
specified.

USE
---

:suggest: X gtk gnome -alsa
:valdesc: space delimited list of USE items

This variable contains options that control the build behavior of several
packages.  More information in ebuild(5).  Possible USE values
can be found in |portdir|/profiles/use.desc and |portdir|/profiles/use.local.desc.

USE_EXPAND
----------

:suggest: LINGUAS VIDEO_CARDS
:valdesc: space separated list of variable names

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".

USE_EXPAND_HIDDEN
-----------------

:valdesc: space separated list of variable names

Names of `USE_EXPAND`_ variables that should not be shown in the verbose merge
list output of the emerge(1) command.

USE_ORDER
---------

:default: env:pkg:conf:defaults:pkginternal
:valdesc: colon separated list of portage config layers

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. *Don't change this unless you know what 
you're doing!* Available layers are:

env
	USE from the current USE environment variable if it exists

pkg
	Per-package USE from /etc/portage/package.use (see portage(5))

conf
	USE from make.conf

defaults
	USE from make.defaults and package.use in the profile (see portage(5))

pkginternal
	USE from ebuild IUSE defaults (flags enabled via a + prefix; see ebuild(5))

REPORTING BUGS
==============

Please report bugs via http://bugs.gentoo.org/

AUTHORS
=======

- Daniel Robbins <drobbins@gentoo.org>
- Nicholas Jones <carpaski@gentoo.org>
- Mike Frysinger <vapier@gentoo.org>
- Saleem Abdulrasool <compnerd@gentoo.org>
- Marius Mauch <genone@gentoo.org>

FILES
=====

/etc/make.conf
	Contains user-supplied variables and overwrites those in make.defaults.

/etc/make.globals
	Contains portage defaults for many variables listed here. Don't change this,
	edit /etc/make.conf instead.

|portdir|/profiles/use.desc
	Contains a list of all global USE flags with brief descriptions.

|portdir|/profiles/use.local.desc
	Contains a list of all local USE variables with brief descriptions.

SEE ALSO
========

- emerge(1)
- portage(5)
- ebuild(1)
- ebuild(5)

.. Substitutions:
.. |accept_keywords| replace:: ~x86
.. |cflags| replace:: -march=i686 -O2 -pipe
.. |chost| replace:: i686-gentoo-linux-gnu
.. |portdir| replace:: /usr/portage