This handbook has been replaced by a newer version and is not maintained anymore.
[ << ]
[ < ]
[ Home ]
[ > ]
[ >> ]
1. Files and Directories
1.a. Portage Files
Portage comes with a default configuration stored in
/etc/make.globals. When you take a look at it, you'll notice that
all Portage configuration is handled through variables. What variables Portage
listens to and what they mean are described later.
Since many configuration directives differ between architectures, Portage also
has a default configuration file inside your profile:
/etc/make.profile/make.defaults. We'll explain more about profiles
and the /etc/make.profile directory later on.
If you're planning on changing a configuration variable, don't alter
/etc/make.globals or /etc/make.profile/make.defaults.
Instead use /etc/make.conf which has precedence over
the previous files. You'll also find a /etc/make.conf.example. As
the name implies, this is merely an example file - Portage does not read in
You can also define a Portage configuration variable as an environment variable,
but we don't recommend this.
We've already encountered the /etc/make.profile directory. Well,
this isn't exactly a directory but a symbolic link to a profile, by default one
inside /usr/portage/profiles although you can create your own
profiles elsewhere and point to them. The profile this symlink points to is the
profile to which your system adheres.
A profile contains architecture-specific information for Portage, such as a
list of packages that belong to the system corresponding with that profile,
a list of packages that don't work (or are masked-out) for that profile, etc.
When you need to override Portage's behaviour regarding the installation of
software, you will end up editing files within /etc/portage. You
are highly recommended to use files within /etc/portage and
highly discouraged to override the behaviour through environment
Within /etc/portage you can create the following files:
package.mask which lists the packages you never want Portage to
package.unmask which lists the packages you want to be able to
install even though the Gentoo developers highly discourage you from
package.keywords which lists the packages you want to be able
to install even though the package hasn't been found suitable for your
system or architecture (yet)
package.use which lists the USE flags you want to use for
certain packages without having the entire system use those USE flags
More information about the /etc/portage directory and a full list
of possible files you can create can be found in the Portage man page:
Code Listing 1.1: Reading the Portage man page
$ man portage
Changing Portage File & Directory Locations
The previously mentioned configuration files cannot be stored elsewhere -
Portage will always look for those configuration files at those exact locations.
However, Portage uses many other locations for various purposes: build
directory, source code storage, Portage tree location, ...
All these purposes have well-known default locations but can be altered to your
own taste through /etc/make.conf. The rest of this chapter explains
what special-purpose locations Portage uses and how to alter their placement on
This document isn't meant to be used as a reference though. If you need 100%
coverage, please consult the Portage and make.conf man pages:
Code Listing 1.2: Reading the Portage and make.conf man pages
$ man portage
$ man make.conf
1.b. Storing Files
The Portage Tree
The Portage tree default location is /usr/portage. This is defined
by the PORTDIR variable. When you store the Portage tree elsewhere (by altering
this variable), don't forget to change the /etc/make.profile
symbolic link accordingly.
If you alter the PORTDIR variable, you might want to alter the following
variables as well since they will not notice the PORTDIR change. This is due to
how Portage handles variables: PKGDIR, DISTDIR, RPMDIR.
Even though Portage doesn't use prebuilt binaries by default, it has extensive
support for them. When you ask Portage to work with prebuilt packages, it will
look for them in /usr/portage/packages. This location is defined by
the PKGDIR variable.
Application source code is stored in /usr/portage/distfiles by
default. This location is defined by the DISTDIR variable.
Even though Portage cannot use RPM files, it is able to generate them using the
ebuild command (see The Ebuild
Application). The default location where Portage stores RPM files is
/usr/portage/rpm and is defined by the RPMDIR variable.
1.c. Building Software
Temporary Portage Files
Portage's temporary files are stored in /var/tmp by default. This
is defined by the PORTAGE_TMPDIR variable.
If you alter the PORTAGE_TMPDIR variable, you might want to alter the following
variables as well since they will not notice the PORTAGE_TMPDIR change. This
is due to how Portage handles variables: BUILD_PREFIX.
Portage creates specific build directories for each package it emerges inside
/var/tmp/portage. This location is defined by the BUILD_PREFIX
Live Filesystem Location
By default Portage installs all files on the current filesystem
(/), but you can change this by setting the ROOT environment
variable. This is useful when you want to create new build images.
1.d. Logging Features
Portage can create per-ebuild logfiles, but only when the PORT_LOGDIR variable
is set to a location that is writable by Portage (the portage user). By default
this variable is unset.
[ << ]
[ < ]
[ Home ]
[ > ]
[ >> ]
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.