1. Files and Directories

Portage comes with a default configuration stored in
/usr/share/portage/config/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 default configuration files which are part of your profile. Your profile is
pointed to by the /etc/portage/make.profile symlink; Portage'
configurations are set in the make.defaults files of your profile
and all parent profiles. We'll explain more about profiles
and the /etc/portage/make.profile directory later on.

If you're planning on changing a configuration variable, don't alter
/usr/share/portage/config/make.globals or make.defaults. Instead use
/etc/portage/make.conf which has precedence over the previous
files. You'll also find a /usr/share/portage/config/make.conf.example.
As the name implies, this is merely an example file - Portage does not read
in this file.

You can also define a Portage configuration variable as an environment variable,
but we don't recommend this.

We've already encountered the /etc/portage/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
variables!

Within /etc/portage you can create the following files:

package.mask which lists the packages you never want Portage to
install

package.unmask which lists the packages you want to be able to
install even though the Gentoo developers highly discourage you from
emerging them

package.accept_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

These don't have to be files; they can also be directories that contain one file
per package. 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:

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/portage/make.conf. The rest of this chapter
explains what special-purpose locations Portage uses and how to alter their
placement on your filesystem.

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:

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/portage/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.

Portage stores the state of your system (what packages are installed, what files
belong to which package, ...) in /var/db/pkg. Do not alter
these files manually! It might break Portage's knowledge of your system.

The Portage cache (with modification times, virtuals, dependency tree
information, ...) is stored in /var/cache/edb. This location really
is a cache: you can clean it if you are not running any portage-related
application at that moment.

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 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. If you don't set PORT_LOGDIR, then you won't receive
any build logs with the current logging system, though you may receive some
logs from the new elog. If you do have PORT_LOGDIR defined and you use
elog, you will receive build logs and any logs saved by elog, as explained
below.

Portage offers fine-grained control over logging through the use of
elog:

PORTAGE_ELOG_CLASSES: This is where you set what kinds of messages to be
logged. You can use any space-separated combination of info,
warn, error, log, and qa.

info: Logs "einfo" messages printed by an ebuild

warn: Logs "ewarn" messages printed by an ebuild

error: Logs "eerror" messages printed by an ebuild

log: Logs the "elog" messages found in some ebuilds

qa: Logs the "QA Notice" messages printed by an ebuild

PORTAGE_ELOG_SYSTEM: This selects the module(s) to process the log messages.
If left empty, logging is disabled. You can use any space-separated
combination of save, custom, syslog, mail,
save_summary, and mail_summary. You must select at least one
module in order to use elog.

save: This saves one log per package in
$PORT_LOGDIR/elog, or /var/log/portage/elog if
$PORT_LOGDIR is not defined.

custom: Passes all messages to a user-defined command in
$PORTAGE_ELOG_COMMAND; this will be discussed later.

syslog: Sends all messages to the installed system logger.

mail: Passes all messages to a user-defined mailserver in
$PORTAGE_ELOG_MAILURI; this will be discussed later. The mail features
of elog require >=portage-2.1.1.

save_summary: Similar to save, but it merges all messages
in $PORT_LOGDIR/elog/summary.log, or
/var/log/portage/elog/summary.log if $PORT_LOGDIR is not
defined.

mail_summary: Similar to mail, but it sends all messages
in a single mail when emerge exits.

PORTAGE_ELOG_COMMAND: This is only used when the custom module is
enabled. Here is where you specify a command to process log messages. Note
that you can make use of two variables: ${PACKAGE} is the package name and
version, while ${LOGFILE} is the absolute path to the logfile. Here's one
possible usage:

PORTAGE_ELOG_MAILFROM: Allows you to set the "from" address of log mails;
defaults to "portage" if unset.

PORTAGE_ELOG_MAILSUBJECT: Allows you to create a subject line for log
mails. Note that you can make use of two variables: ${PACKAGE} will display
the package name and version, while ${HOST} is the fully qualified domain
name of the host Portage is running on.

Here's one possible use:

PORTAGE_ELOG_MAILSUBJECT="package \${PACKAGE} was merged on \${HOST}
with some messages"

Important:
If you used enotice with Portage-2.0.*, you must completely remove
enotice, as it is incompatible with elog.