PORTAGE(5) Portage PORTAGE(5)NAMEportage - the heart of Gentoo
DESCRIPTION
The current portage code uses many different configuration files, most
of which are unknown to users and normal developers. Here we will try
to collect all the odds and ends so as to help users more effectively
utilize portage. This is a reference only for files which do not
already have a man page.
All files in the make.profile directory may be tweaked via parent pro‐
files when using cascading profiles. For more info, please see
http://www.gentoo.org/proj/en/releng/docs/cascading-profiles.xml
Note: If you are looking for information on how to emerge something,
please see emerge(1).
SYNOPSIS
/etc/portage/make.profile/ or /etc/make.profile/
site-specific overrides go in /etc/portage/profile/
deprecated
eapi
make.defaults
packages
packages.build
package.accept_keywords
package.keywords
package.mask
package.provided
package.unmask
package.use
package.use.force
package.use.mask
package.use.stable.force
package.use.stable.mask
parent
profile.bashrc
use.force
use.mask
use.stable.mask
use.stable.force
virtuals
/etc/portage/
bashrc
categories
color.map
license_groups
make.conf(5)
mirrors
modules
package.accept_keywords
package.accept_restrict
package.env
package.keywords
package.license
package.mask
package.properties
package.unmask
package.use
repos.conf
/etc/portage/env/
package-specific bashrc files
/etc/portage/profile/
site-specific overrides of /etc/portage/make.profile/
/etc/portage/sets/
user-defined package sets
/usr/portage/metadata/
layout.conf
/usr/portage/profiles/
arch.list
categories
info_pkgs
info_vars
license_groups
make.defaults
package.mask
package.unmask
package.use
package.use.force
package.use.mask
package.use.stable.force
package.use.stable.mask
profiles.desc
repo_name
thirdpartymirrors
use.desc
use.force
use.local.desc
use.mask
use.stable.mask
use.stable.force
/usr/share/portage/config/
make.globals
repos.conf
/var/cache/edb/
misc internal cache files
/var/db/pkg/
database to track installed packages
/var/lib/portage/
config
world
world_sets
GLOSSARY
In the following sections, some terminology may be foreign to you or
used with meaning specific to Portage. Please see the referenced man‐
pages for more detailed explanations.
DEPEND atom
An atom is either of the form category/package or con‐
sists of an operator followed by category/package fol‐
lowed by a hyphen and a version specification. An atom
might be suffixed by a slot specification.
More reading: ebuild(5)
Extended Atom Syntax
The following atom syntax extensions are only supported
in user configuration files and command line arguments
for programs such as emerge(1):
Repository Constraints
Atoms with repository constraints have a '::' sep‐
arator appended to the right side, followed by a
repository name. Each repository name should cor‐
respond to the value of a repo_name entry from one
of the repositories that is configured via the
PORTDIR or PORTDIR_OVERLAY variables (see
make.conf(5)).
Examples:
# match sed from the 'gentoo' repository
sys-apps/sed::gentoo
# match kdelibs from the 'kde-testing' repository
kde-base/kdelibs::kde-testing
# match empathy from the 'gnome' repository
net-im/empathy::gnome
Wildcard Patterns
Atoms containing wildcard patterns are of the form
category/package, where the special '*' wildcard
character substitutes for an arbitrary number of
normal characters. More than one '*' character is
allowed, but not two next to each other.
Examples:
# match anything with a version containing 9999, which can be used in
# package.mask to prevent emerge --autounmask from selecting live ebuilds
=*/*-*9999*
# match anything with a version containing _beta
=*/*-*_beta*
# match anything from the 'sys-apps' category
sys-apps/*
# match packages named 'zlib' from any category
*/zlib
# match any package from a category that begins with 'net-'
net-*/*
# match any package name from any category
*/*
# match any package from the 'gentoo' repository
*/*::gentoo
KEYWORD
Each architecture has a unique KEYWORD.
More reading: ebuild(5)
virtual
A DEPEND atom that is part of the "virtual" category.
They are used when different packages can satisfy a
dependency and only one of them is needed.
More reading: ebuild(5)SPECIFIC FILE DESCRIPTIONS
/etc/portage/make.profile/ or /etc/make.profile/
This is usually just a symlink to the correct profile in
/usr/portage/profiles/. Since it is part of the portage tree,
it may easily be updated/regenerated by running `emerge --sync`.
It defines what a profile is (usually arch specific stuff). If
you need a custom profile, then you should make your own
make.profile directory and populate it. However, if you just
wish to override some settings, use /etc/portage/profile/ (it
supports all of the same file types that make.profile does,
except parent). Do NOT edit the settings in make.profile because
they WILL be lost with the next `emerge --sync`. If both
/etc/portage/make.profile/ and /etc/make.profile/ exist, then
/etc/portage/make.profile/ will be preferred.
Any file in this directory, directories of other profiles or
top-level "profiles" directory that begins with "package." or
"use." can be more than just a flat file. If it is a directory,
then all the files in that directory will be sorted in ascending
alphabetical order by file name and summed together as if it
were a single file. Note that this behavior is only supported
since portage-2.1.6.7, and it is not included in PMS at this
time.
Example:
${PORTDIR}/profiles/package.mask/removals
${PORTDIR}/profiles/package.mask/testing
deprecated
The existence of this file marks a profile as deprecated,
meaning it is not supported by Gentoo anymore. The first
line must be the profile to which users are encouraged to
upgrade, optionally followed by some instructions
explaining how they can upgrade.
Example:
default-linux/x86/2005.0
# emerge -n '>=sys-apps/portage-2.0.51'
# rm -f /etc/portage/make.profile
# ln -s /usr/portage/profiles/default-linux/alpha/2005.0 /etc/portage/make.profile
eapi The first line of this file specifies the EAPI to which
files in the same directory conform. See ebuild(5) for
information about EAPI and related features. Beginning
with EAPI 5, new USE configuration files are supported:
use.stable.mask, use.stable.force, package.use.sta‐
ble.mask and package.use.stable.force. These files behave
similarly to previously supported USE configuration
files, except that they only influence packages that are
merged due to a stable keyword.
make.defaults
The profile default settings for Portage. The general
format is described in make.conf(5). The make.defaults
for your profile defines a few specific variables too:
ARCH Architecture type (x86/ppc/hppa/etc...).
IUSE_IMPLICIT = [space delimited list of USE flags]
Defines implicit IUSE for ebuilds using EAPI 5 or
later. Flags that come from USE_EXPAND or
USE_EXPAND_UNPREFIXED variables do not belong in
IUSE_IMPLICIT, since USE_EXPAND_VALUES_* variables
are used to define implicit IUSE for those flags.
See ebuild(5) for more information about IUSE.
USERLAND = "GNU"
Support BSD/cygwin/etc...
USE_EXPAND = [space delimited 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 = [space delimited 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_EXPAND_IMPLICIT = [space delimited list of variable
names]
Defines USE_EXPAND and USE_EXPAND_UNPREFIXED vari‐
ables for which the corresponding USE flags may
have implicit IUSE for ebuilds using EAPI 5 or
later.
USE_EXPAND_UNPREFIXED = [space delimited 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_UNPREFIXED="FOO" and
FOO="bar bla" results in USE="bar bla".
USE_EXPAND_VALUES_ARCH = [space delimited list of ARCH
values]
Defines ARCH values used to generate implicit IUSE
for ebuilds using EAPI 5 or later.
USE_EXPAND_VALUES_ELIBC = [space delimited list of ELIBC
values]
Defines ELIBC values used to generate implicit
IUSE for ebuilds using EAPI 5 or later.
USE_EXPAND_VALUES_KERNEL = [space delimited list of KER‐
NEL values]
Defines KERNEL values used to generate implicit
IUSE for ebuilds using EAPI 5 or later.
USE_EXPAND_VALUES_USERLAND = [space delimited list of
USERLAND values]
Defines USERLAND values used to generate implicit
IUSE for ebuilds using EAPI 5 or later.
ELIBC = "glibc"
Support uClibc/BSD libc/etc...
PROFILE_ONLY_VARIABLES = "ARCH"
Prevent critical variables from being changed by
the user in make.conf or the env.
PROFILE_ARCH
Distinguish machines classes that have the same
ARCH. All sparc machines have ARCH=sparc but set
this to either 'sparc32' or 'sparc64'.
BOOTSTRAP_USE
Special USE flags which may be needed when boot‐
strapping from stage1 to stage2.
packages
Provides the list of packages that compose the special
system set.
Format:
- comments begin with # (no inline comments)
- one DEPEND atom per line
- packages to be added to the system set begin with a *
- atoms without * only appear for legacy reasons
Note: In a cascading profile setup, you can remove pack‐
ages in children profiles which were added by parent pro‐
files by prefixing the atom with a '-'.
Example:
# i am a comment !
# pull in a version of glibc less than 2.3
*<sys-libs/glibc-2.3
# pull in any version of bash
*app-shells/bash
# pull in a version of readline earlier than 4.2
*<sys-libs/readline-4.2
packages.build
A list of packages (one per line) that make up a stage1
tarball. Really only useful for stage builders.
package.provided
A list of packages (one per line) that portage should
assume have been provided. Useful for porting to non-
Linux systems. Basically, it's a list that replaces the
emerge --inject syntax.
For example, if you manage your own copy of a 2.6 kernel,
then you can tell portage that 'sys-kernel/development-
sources-2.6.7' is already taken care of and it should get
off your back about it.
Portage will not attempt to update a package that is
listed here unless another package explicitly requires a
version that is newer than what has been listed. Depen‐
dencies that are satisfied by package.provided entries
may cause installed packages satisfying equivalent depen‐
dencies to be removed by emerge(1)--depclean actions
(see the ACTIONS section of the emerge(1) man page for
more information).
Virtual packages (virtual/*) should not be specified in
package.provided, since virtual packages themselves do
not provide any files, and package.provided is intended
to represent packages that do provide files. Depending
on the type of virtual, it may be necessary to add an
entry to the virtuals file and/or add a package that sat‐
isfies a virtual to package.provided.
Format:
- comments begin with # (no inline comments)
- one DEPEND atom per line
- relational operators are not allowed
- must include a version
Example:
# you take care of the kernel
sys-kernel/development-sources-2.6.7
# you installed your own special copy of QT
x11-libs/qt-3.3.0
# you have modular X but packages want monolithic
x11-base/xorg-x11-6.8
package.use.force and package.use.stable.force
Per-package USE flag forcing.
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 '-'.
Format:
- comments begin with # (no inline comments)
- one DEPEND atom per line with space-delimited USE flags
Example:
# force docs for GTK 2.x
=x11-libs/gtk+-2* doc
# unforce mysql support for QT
x11-libs/qt -mysql
package.use.mask and package.use.stable.mask
Per-package USE flag masks.
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 '-'.
Format:
- comments begin with # (no inline comments)
- one DEPEND atom per line with space-delimited USE flags
Example:
# mask docs for GTK 2.x
=x11-libs/gtk+-2* doc
# unmask mysql support for QT
x11-libs/qt -mysql
parent This contains paths to the parent profiles (one per
line). They may be either relative (to the location of
the profile) or absolute. Most commonly this file con‐
tains '..' to indicate the directory above. Utilized
only in cascading profiles.
When multiple parent profiles are specified, they are
inherited in order from the first line to the last.
If layout.conf is new enough, you can also use the
<repo>:<path> syntax. The <repo> is the same string as
is stored in the repo_name file (or omitted to refer to
the current repo), and <path> is a subdir starting at
profiles/.
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.
use.force and use.stable.force
Some USE flags don't make sense to disable under certain
conditions. Here we list forced flags.
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 '-'.
Format:
- comments begin with # (no inline comments)
- one USE flag per line
use.mask and use.stable.mask
Some USE flags don't make sense on some archs (for exam‐
ple altivec on non-ppc or mmx on non-x86), or haven't yet
been tested. Here we list the masked ones.
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 '-'.
Format:
- comments begin with # (no inline comments)
- one USE flag per line
Example:
# mask doc
doc
# unmask mysql
-mysql
virtuals
The virtuals file controls default preferences for virtu‐
als that are defined via the PROVIDE ebuild variable (see
ebuild(5)). Since Gentoo now uses GLEP 37 virtuals
instead of PROVIDE virtuals, the virtuals file is irrele‐
vant for all Gentoo ebuilds. However, it is still possi‐
ble for third-parties to distribute ebuilds that make use
of PROVIDE.
Format:
- comments begin with # (no inline comments)
- one virtual and DEPEND atom base pair per line
Example:
# use net-mail/ssmtp as the default mta
virtual/mta net-mail/ssmtp
# use app-dicts/aspell-en as the default dictionary
virtual/aspell-dict app-dicts/aspell-en
/etc/portage/
Any file in this directory that begins with "package." or is
repos.conf can be more than just a flat file. If it is a direc‐
tory, then all the files in that directory will be sorted in
ascending alphabetical order by file name and summed together as
if it were a single file.
Example:
/etc/portage/package.accept_keywords/common
/etc/portage/package.accept_keywords/e17
/etc/portage/package.accept_keywords/kde
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.
Additional package-specific bashrc files can be created
in /etc/portage/env.
categories
A simple list of valid categories that may be used in
/usr/portage, PORTDIR_OVERLAY, and PKGDIR (see
make.conf(5)). This allows for custom categories to be
created.
Format:
- one category per line
Example:
app-hackers
media-other
color.map
Contains variables customizing colors. See color.map(5).
make.conf
The global custom settings for Portage. See make.conf(5).
mirrors
Whenever portage encounters a mirror:// style URI it will
look up the actual hosts here. If the mirror set is not
found here, it will check the global 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" or
RESTRICT="fetch".
Format:
- comments begin with # (no inline comments)
- mirror type followed by a list of hosts
Example:
# local private mirrors used only by my company
local ftp://192.168.0.3/mirrors/gentoo http://192.168.0.4/distfiles
# people in japan would want to use the japanese mirror first
sourceforge http://keihanna.dl.sourceforge.net/sourceforge
# people in tawain would want to use the local gnu mirror first
gnu ftp://ftp.nctu.edu.tw/UNIX/gnu/
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.
Example:
portdbapi.auxdbmodule = portage.cache.sqlite.database
After changing the portdbapi.auxdbmodule setting, it may
be necessary to transfer or regenerate metadata cache.
Users of the rsync tree need to run `emerge --metadata`
if they have enabled FEATURES="metadata-transfer" in
make.conf(5). In order to regenerate metadata for reposi‐
tories listed in PORTDIR_OVERLAY or a cvs tree, run
`emerge --regen` (see emerge(1)). If you use something
like the sqlite module and want to keep all metadata in
that format alone (useful for querying), enable FEA‐
TURES="metadata-transfer" in make.conf(5).
package.accept_keywords and package.keywords
Per-package ACCEPT_KEYWORDS. Useful for mixing unstable
packages in with a normally stable system or vice versa.
This will allow ACCEPT_KEYWORDS to be augmented for a
single package. If both package.accept_keywords and pack‐
age.keywords are present, both of them will be used, and
values from package.accept_keywords will override values
from package.keywords. The package.accept_keywords file
is intended to replace the package.keywords file, since
profiles support a different form of package.keywords
which modifies effective KEYWORDS (rather than
ACCEPT_KEYWORDS).
Format:
- comment lines begin with # (no inline comments)
- one DEPEND atom per line followed by additional KEYWORDS
- lines without any KEYWORDS imply unstable host arch
Example:
# always use unstable libgd
media-libs/libgd ~x86
# only use stable mplayer
media-video/mplayer -~x86
# always use unstable netcat
net-analyzer/netcat
Note:
In addition to the normal values from ACCEPT_KEYWORDS
package.keywords supports three special tokens:
* package is visible if it is stable on any architecture
~* package is visible if it is in testing on any architecture
** package is always visible (KEYWORDS are ignored completely)
Additional Note: If you encounter the -* KEYWORD, this
indicates that the package is known to be broken on all
systems which are not otherwise listed in KEYWORDS. For
example, a binary only package which is built for x86
will look like:
games-fps/quake3-demo-1.11.ebuild:KEYWORDS="-* x86"
If you wish to accept this package anyways, then use one
of the other keywords in your package.accept_keywords
like this:
games-fps/quake3-demo x86
package.accept_restrict
This will allow ACCEPT_RESTRICT (see make.conf(5)) to be
augmented for a single package.
Format:
- comment lines begin with # (no inline comments)
- one DEPEND atom per line followed by additional RESTRICT tokens
package.env
Per-package environment variable settings. Entries refer
to environment files that are placed in the
/etc/portage/env/ directory and have the same format as
make.conf(5). Note that these files are interpreted much
earlier than the package-specific bashrc files which are
described in a later section about /etc/portage/env/.
Beginners should be careful to recognize the difference
between these two types of files. When environment vari‐
able settings are all that's needed, package.env is the
recommended approach to use.
Format:
- comment lines begin with # (no inline comments)
- one DEPEND atom per line followed by name(s) of environment file(s)
Example:
# use environment variables from /etc/portage/env/glibc.conf for the glibc package
sys-libs/glibc glibc.conf
package.license
This will allow ACCEPT_LICENSE (see make.conf(5)) to be
augmented for a single package.
Format:
- comment lines begin with # (no inline comments)
- one DEPEND atom per line followed by additional licenses or groups
package.mask
A list of package atoms to mask. Useful if specific ver‐
sions of packages do not work well for you. For example,
you swear by the Nvidia drivers, but only versions ear‐
lier than 1.0.4496. No problem!
Format:
- comment lines begin with # (no inline comments)
- one DEPEND atom per line
Example:
# mask out versions 1.0.4496 of the nvidia
# drivers and later
>=media-video/nvidia-kernel-1.0.4496
>=media-video/nvidia-glx-1.0.4496
package.properties
This will allow ACCEPT_PROPERTIES (see make.conf(5)) to
be augmented for a single package.
Format:
- comment lines begin with # (no inline comments)
- one DEPEND atom per line followed by additional properties
package.unmask
Just like package.mask above, except here you list pack‐
ages you want to unmask. Useful for overriding the
global package.mask file (see above). Note that this
does not override packages that are masked via KEYWORDS.
package.use
Per-package USE flags. Useful for tracking local USE
flags or for enabling USE flags for certain packages
only. Perhaps you develop GTK and thus you want documen‐
tation for it, but you don't want documentation for QT.
Easy as pie my friend!
Format:
- comments begin with # (no inline comments)
- one DEPEND atom per line with space-delimited USE flags
Example:
# turn on docs for GTK 2.x
=x11-libs/gtk+-2* doc
# disable mysql support for QT
x11-libs/qt -mysql
repos.conf
Specifies site-specific repository configuration informa‐
tion.
Format:
- comments begin with # (no inline comments)
- configuration of each repository is specified in a section starting with "[${repository_name}]"
- attributes are specified in "${attribute} = ${value}" format
Attributes supported in DEFAULT section:
main-repo
Specifies main repository.
eclass-overrides
Makes all repositories inherit eclasses
from specified repositories.
Setting this attribute is generally not
recommended since resulting changes in
eclass inheritance may trigger performance
issues due to invalidation of metadata
cache.
When 'force = eclass-overrides' attribute
is not set, egencache(1), emirrordist(1)
and repoman(1) ignore this attribute, since
operations performed by these tools are
inherently not site-specific.
force Specifies names of attributes, which should
be forcefully respected by egencache(1),
emirrordist(1) and repoman(1).
Valid values: aliases, eclass-overrides,
masters
Attributes supported in sections of repositories:
aliases
Specifies aliases of given repository.
Setting this attribute is generally not
recommended since resulting changes in
eclass inheritance may trigger performance
issues due to invalidation of metadata
cache.
When 'force = aliases' attribute is not
set, egencache(1), emirrordist(1) and repo‐
man(1) ignore this attribute, since opera‐
tions performed by these tools are inher‐
ently not site-specific.
eclass-overrides
Makes given repository inherit eclasses
from specified repositories.
Setting this attribute is generally not
recommended since resulting changes in
eclass inheritance may trigger performance
issues due to invalidation of metadata
cache.
When 'force = eclass-overrides' attribute
is not set, egencache(1), emirrordist(1)
and repoman(1) ignore this attribute, since
operations performed by these tools are
inherently not site-specific.
force Specifies names of attributes, which should
be forcefully respected by egencache(1),
emirrordist(1) and repoman(1).
Valid values: aliases, eclass-overrides,
masters
location
Specifies location of given repository.
masters
Specifies master repositories of given
repository.
Setting this attribute is generally not
recommended since resulting changes in
eclass inheritance may trigger performance
issues due to invalidation of metadata
cache.
When 'force = masters' attribute is not
set, egencache(1), emirrordist(1) and repo‐
man(1) ignore this attribute, since opera‐
tions performed by these tools are inher‐
ently not site-specific.
priority
Specifies priority of given repository.
sync-cvs-repo
Specifies CVS repository.
sync-type
Specifies type of synchronization performed
by `emerge --sync`.
Valid non-empty values: cvs, git, rsync
This attribute can be set to empty value to
disable synchronization of given reposi‐
tory. Empty value is default.
sync-uri
Specifies URI of repository used for syn‐
chronization performed by `emerge --sync`.
This attribute can be set to empty value to
disable synchronization of given reposi‐
tory. Empty value is default.
Syntax:
cvs: [cvs://]:access_method:[user‐
name@]hostname[:port]:/path
git:
(git|git+ssh|http|https)://[user‐
name@]hostname[:port]/path
rsync: (rsync|ssh)://[user‐
name@]hostname[:port]/(module|path)
Examples:
rsync://private-mir‐
ror.com/portage-module
rsync://rsync-user@private-mir‐
ror.com:873/gentoo-portage
ssh://ssh-user@192.168.0.1:22/usr/portage
ssh://ssh-user@192.168.0.1:22/\${HOME}/portage-stor‐
age
Note: For the ssh:// scheme, key-based
authentication might be of interest.
Example:
[DEFAULT]
# make gentoo the main repository, which makes it the default master
# repository for repositories that do not specify masters
main-repo = gentoo
# make all repositories inherit eclasses from the java-overlay and
# java-experimental repositories, with eclasses from java-experimental
# taking precedence over those from java-overlay
eclass-overrides = java-overlay java-experimental
[gentoo]
# repos with higher priorities are preferred when ebuilds with equal versions
# are found in multiple repos (see the `emerge --info --verbose` repo
# display for a listing of repos and their corresponding priorities).
priority = 9999
# disable all eclass overrides for ebuilds from the gentoo repository
eclass-overrides =
# when processing metadata/layout.conf from other repositories, substitute
# 'gentoo' in place of references to repositories named 'foo' and 'bar',
# and discard the 'baz' alias contained in gentoo's layout.conf
aliases = foo bar -baz
[kde-testing]
# override the metadata/layout.conf masters setting from the kde-testing repo
masters = gentoo kde
[python]
# override the metadata/layout.conf masters setting from the python repo,
# so that settings won't be inherited from those masters, and so that
# those master repos won't be required as dependencies (the user must
# ensure that any required dependencies such as eclasses are satisfied)
masters =
# Repository 'gentoo' synchronized using CVS
[gentoo]
location = /usr/portage
sync-type = cvs
sync-uri = :pserver:anonymous@anoncvs.gentoo.org:/var/cvsroot
sync-cvs-repo = gentoo-x86
/etc/portage/env/
In this directory additional package-specific bashrc files can
be created. Note that if package-specific environment variable
settings are all that's needed, then /etc/portage/package.env
should be used instead of the bashrc approach that is described
here. Also note that special variables such as FEATURES and
INSTALL_MASK will not produce the intended results if they are
set in bashrc, and therefore /etc/portage/package.env should be
used instead. Lastly, note that these files are interpreted much
later than the portage environment file package.env.
Portage will source all of these bashrc files after
/etc/portage/bashrc in the following order:
1. /etc/portage/env/${CATEGORY}/${PN}
2. /etc/portage/env/${CATEGORY}/${PN}:${SLOT}
3. /etc/portage/env/${CATEGORY}/${P}
4. /etc/portage/env/${CATEGORY}/${PF}
/etc/portage/sets/
For each file in this directory, a package set is created with
its name corresponding to the name of the file. Each file should
contain a list of package atoms and nested package sets, one per
line. When a package set is referenced as an emerge(1) argument
or when it is referenced as a nested package set (inside of
another package set), the set name is prefixed with @.
Also see /var/lib/portage/world_sets and the emerge(1)--list-sets option.
/usr/portage/metadata/
layout.conf
Specifies information about the repository layout. Site-
specific overrides to layout.conf settings may be speci‐
fied in /etc/portage/repos.conf. Settings in repos.conf
take precedence over settings in layout.conf, except
tools such as repoman(1) and egencache(1) ignore
"aliases", "eclass-overrides" and "masters" attributes
set in repos.conf since their operations are inherently
not site-specific.
Format:
- comments begin with # (no inline comments)
- attributes are specified in "${attribute} = ${value}" format
Supported attributes.
aliases
Behaves like an "aliases" attribute in
repos.conf.
eapis-banned
List of EAPIs which are not allowed in this
repo.
eapis-deprecated
List of EAPIs which are allowed but gener‐
ate warnings when used.
masters
Names of repositories which satisfy depen‐
dencies on eclasses and/or ebuilds. Each
repository name should correspond the value
of a repo_name entry from one of the repos‐
itories that is configured via the PORTDIR
or PORTDIR_OVERLAY variables (see
make.conf(5)). Repositories listed toward
the right of the masters list take prece‐
dence over those listed toward the left of
the list.
repo-name = <value of profiles/repo_name>
The name of this repository (overrides pro‐
files/repo_name if it exists).
sign-commits = [true|false]
Boolean value whether we should sign com‐
mits in this repo.
sign-manifests = [true|false]
Boolean value whether we should sign Mani‐
fest files in this repo.
thin-manifests = [true|false]
Boolean value whether Manifest files con‐
tain only DIST entries.
use-manifests = [strict|true|false]
How Manifest files get used. Possible val‐
ues are "strict" (require an entry for
every file), "true" (if an entry exists for
a file, enforce it), or "false" (don't
check Manifest files at all).
manifest-hashes
List of hashes to generate/check in Mani‐
fest files. Valid hashes depend on the
current version of portage; see the
portage.const.MANIFEST2_HASH_FUNCTIONS con‐
stant for the current list.
update-changelog = [true|false]
The default setting for repoman's
--echangelog option.
cache-formats = [pms] [md5-dict]
The cache formats supported in the metadata
tree. There is the old "pms" format and
the newer/faster "md5-dict" format.
Default is to detect dirs.
profile-formats = [pms|portage-1|portage-2]
Control functionality available to profiles
in this repo such as which files may be
dirs, or the syntax available in parent
files. Use "portage-2" if you're unsure.
The default is "portage-1-compat" mode
which is meant to be compatible with old
profiles, but is not allowed to be opted
into directly.
Example:
# Specify the repository name (overriding profils/repo_name).
repo-name = foo-overlay
# eclasses provided by java-overlay take precedence over identically named
# eclasses that are provided by gentoo
masters = gentoo java-overlay
# indicate that this repo can be used as a substitute for foo-overlay
aliases = foo-overlay
# indicate that ebuilds with the specified EAPIs are banned
eapis-banned = 0 1
# indicate that ebuilds with the specified EAPIs are deprecated
eapis-deprecated = 2 3
# sign commits in this repo, which requires Git >=1.7.9, and
# key configured by `git config user.signingkey key_id`
sign-commits = true
# do not sign Manifest files in this repo
sign-manifests = false
# Manifest files only contain DIST entries
thin-manifests = true
# indicate that this repo requires manifests for each package, and is
# considered a failure if a manifest file is missing/incorrect
use-manifests = strict
# customize the set of hashes generated for Manifest entries
manifest-hashes = SHA256 SHA512 WHIRLPOOL
# indicate that this repo enables repoman's --echangelog=y option automatically
update-changelog = true
# indicate that this repo contains both md5-dict and pms cache formats,
# which may be generated by egencache(1)
cache-formats = md5-dict pms
# indicate that this repo contains profiles that may use directories for
# package.mask, package.provided, package.use, package.use.force,
# package.use.mask, package.use.stable.force, package.use.stable.mask,
# use.force, use.mask, use.stable.force, and use.stable.mask.
# profile-formats = portage-1
# indicate that paths such as 'gentoo:targets/desktop' or ':targets/desktop' in
# profile parent files can be used to express paths relative to the root
# 'profiles' directory of a repository (when the repo name is omitted before
# the colon, it refers to the current repository the parent file is inside)
profile-formats = portage-2
/usr/portage/profiles/
Global Gentoo settings that are controlled by the developers.
To override these settings, you can use the files in
/etc/portage/.
arch.list
A list of all valid KEYWORDS. This does not include mod‐
ifiers.
Format:
- one KEYWORD per line
Example:
x86
ppc
sparc
categories
A simple list of valid categories that may be used in
/usr/portage, PORTDIR_OVERLAY, and PKGDIR (see
make.conf(5)).
Format:
- one category per line
Example:
app-admin
dev-lang
games-strategy
sys-kernel
info_pkgs
A list of all the packages which will be displayed when
you run `emerge info`.
info_vars
A list of all the variables which will be displayed when
you run `emerge info`.
license_groups
This contains groups of licenses that may be specifed in
the ACCEPT_LICENSE variable (see make.conf(5)). Refer to
GLEP 23 for further information: http://www.gen‐
too.org/proj/en/glep/glep-0023.html.
Format:
- comments begin with # (no inline comments)
- one group name, followed by list of licenses and nested groups
- nested groups are prefixed with the '@' symbol
Example:
# The FSF-APPROVED group includes the entire GPL-COMPATIBLE group and more.
FSF-APPROVED @GPL-COMPATIBLE Apache-1.1 BSD-4 MPL-1.0 MPL-1.1
# The GPL-COMPATIBLE group includes all licenses compatible with the GNU GPL.
GPL-COMPATIBLE Apache-2.0 BSD BSD-2 GPL-2 GPL-3 LGPL-2.1 LGPL-3 X11 ZLIB
package.accept_keywords
Per-package ACCEPT_KEYWORDS for profiles. This has the
same format and behavior as /etc/portage/pack‐
age.accept_keywords, including the ability to list atoms
without any keywords in order to accept unstable variants
of all stable keywords listed in ACCEPT_KEYWORDS.
package.keywords
Per-profile KEYWORDS. Useful for cases in which the
effective KEYWORDS of a given package should vary depend‐
ing on which profile the user has selected.
Format:
- comment lines begin with # (no inline comments)
- one DEPEND atom per line followed by additional KEYWORDS
Example:
# add stable keyword to libgd
media-libs/libgd x86
# remove stable keyword from mplayer and add unstable keyword
media-video/mplayer -x86 ~x86
# remove all keywords from netcat
net-analyzer/netcat -*
package.mask
This contains a list of DEPEND atoms for packages that
should not be installed in any profile. Useful for
adding the latest KDE betas and making sure no one acci‐
dentally upgrades to them. Also useful for quickly mask‐
ing specific versions due to security issues. ALWAYS
include a comment explaining WHY the package has been
masked and WHO is doing the masking.
Format:
- comments begin with # (no inline comments)
- one DEPEND atom per line
Example:
# masked for security reasons
<sys-libs/zlib-1.1.4
# <caleb@gentoo.org> (10 Sep 2003)
# new kde betas
=kde-base/kde-3.2.0_beta1
=kde-base/kdeaccessibility-3.2.0_beta1
profiles.desc
List all the current stable and development profiles. If
a profile is listed here, then it will be checked by
repoman. Format:
- comments begin with # (no inline comments)
- one profile list per line in format: arch dir status
- arch must be listed in arch.list
- dir is relative to profiles.desc
- status must be 'stable', 'dev', or 'exp'
Example:
alpha default/linux/alpha/10.0 stable
m68k default/linux/m68k/10.0 dev
x86 default/linux/x86/10.0 stable
x86-linux prefix/linux/x86 exp
repo_name
The first line of the file should define a unique reposi‐
tory name. The name may contain any of the characters
[A-Za-z0-9_-]. It must not begin with a hyphen. If the
repo-name attribute is specified in layout.conf, then
that setting will take precedence.
thirdpartymirrors
Controls the mapping of mirror:// style URIs to actual
lists of mirrors. Keeps us from overloading a single
server.
Format:
- comments begin with # (no inline comments)
- mirror type followed by a list of hosts
Example:
sourceforge http://aleron.dl.sourceforge.net/sourceforge http://unc.dl.sourceforge.net/sourceforge
gentoo http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles/ ftp://ftp.gtlib.cc.gatech.edu/pub/gentoo/distfiles
kernel http://www.kernel.org/pub http://www.us.kernel.org/pub
use.desc
All global USE flags must be listed here with a descrip‐
tion of what they do.
Format:
- comments begin with # (no inline comments)
- use flag - some description
Example:
3dfx - Adds support for 3dfx video cards
acl - Adds support for Access Control Lists
doc - Adds extra documentation
use.local.desc
All local USE flags are listed here along with the pack‐
age and a description. This file is automatically gener‐
ated from the metadata.xml files that are included with
each individual package. Refer to GLEP 56 for further
information: http://www.gen‐
too.org/proj/en/glep/glep-0056.html.
Format:
- comments begin with # (no inline comments)
- package:use flag - description
Example:
app-editors/nano:justify - Toggles the justify option
dev-libs/DirectFB:fusion - Adds Multi Application support
games-emulation/xmess:net - Adds network support
/usr/share/portage/config/
make.globals
The global default settings for Portage. This comes from
the portage package itself. Settings in make.conf or
package.env override values set here. The format is
described extensively in make.conf(5).
repos.conf
The default configuration of repositories for Portage.
This comes from the portage package itself. Settings in
/etc/portage/repos.conf override values set here. The
format is described extensively in section for
/etc/portage/repos.conf.
/var/cache/edb/
This directory is used to store internal portage cache files.
The names and purpose of these files are not documented on pur‐
pose so as to keep down bitrot as internals change. If you
aren't working on portage internally, then the details most
likely do not matter to you.
This entire directory can be safely deleted. It is highly rec‐
ommended you do not do this however as it can be a time consum‐
ing process to generate them all again.
/var/db/pkg/
All installed package information is recorded here. If portage
thinks you have a package installed, it is usually because it is
listed here.
The format follows somewhat closely that of the portage tree.
There is a directory for each category and a package-version
subdirectory for each package you have installed.
Inside each package directory are misc files that describe the
installed contents of the package as well as build time informa‐
tion (so that the package can be unmerged without needing the
portage tree).
The exact file contents and format are not described here again
so that things can be changed quickly. Generally though there
is one file per environment variable that "matters" (like
CFLAGS) with the contents stored inside of it. Another common
file is the CONTENTS file which lists the path and hashes of all
objects that the package installed onto your system.
/var/lib/portage/
config Hashes which are used to determine whether files in con‐
fig protected directories have been modified since being
installed. Files which have not been modified will auto‐
matically be unmerged.
world Every time you emerge a package, the package that you
requested is recorded here. Then when you run `emerge
world -up`, the list of packages is read from this file.
Note that this does not mean that the packages that were
installed as dependencies are listed here. For example,
if you run `emerge mod_wsgi` and you do not have apache
already, then "www-apache/mod_wsgi" is recorded in the
world file but "www-servers/apache" is not. For more
information, review emerge(1).
Format:
- one DEPEND atom base per line
Example:
games-misc/fortune-mod-gentoo-dev
dev-libs/uclibc
app-cdr/cdemu
world_sets
This is like the world file but instead of package atoms
it contains packages sets which always begin with the @
character. Use /etc/portage/sets/ to define user package
sets.
Example:
@kde
REPORTING BUGS
Please report bugs via http://bugs.gentoo.org/
AUTHORS
Marius Mauch <genone@gentoo.org>
Mike Frysinger <vapier@gentoo.org>
Drake Wyrm <wyrm@haell.com>
Arfrever Frehtes Taifersar Arahesis <arfrever@apache.org>
SEE ALSOemerge(1), ebuild(1), ebuild(5), make.conf(5), color.map(5)Portage 2.2.8-r1 Dec 2013 PORTAGE(5)