/etc/portage/package.env

/etc/portage/env can contain files to be called during the installation of specific packages, or files used to set Portage's environment variables on a per-package basis.

To have a file called when emerging a specific package, it should be named following the pattern "/etc/portage/env/<category>/<package_name>" (versions can be included, see portage man page), the contents being as in /etc/portage/bashrc; the contents will be parsed as a bash script. These files can hook into specific phases of the emerge process.

If all that is needed is to set environment variables, use a free-form file name directly in /etc/portage/env, then add a line in /etc/portage/package.env with a package atom followed by the chosen file name, like in the following examples. This allows the same environment settings to be used for multiple packages, if needed, or settings to be "mix and matched". Variables can be set in same manner as in make.conf(5):

It supports simple shell-like expansion of the form var="${var}", the source keyword and variable substitution, but not some of the more advanced BASH features like arrays and special parameter expansions. For more details, see the Simple lexical analysis documentation: https://docs.python.org/3/library/shlex.html. Note that if you source files, they need to be in the same shlex syntax for portage to read them.

See also
There are two separate sections in the portage man page that cover in detail the use of this directory.

/etc/portage/package.env can be a file, or can be created as a directory that can contain multiple files.

Be aware that certain variables in /etc/portage/make.conf are incremental variables. This means if the variable is already specified in /etc/portage/make.conf then Portage will read the values set in make.conf, and then read the values set in files beneath the /etc/portage/env directory. In other words if FEATURES="ccache" in make.conf, and FEATURES="-ccache" in package/env/disable-ccache.conf, then Portage will see FEATURES as set to FEATURES="ccache -ccache" at emerge time for any packages which disable-ccache.conf is applied. This ultimately results in ccache being disabled for packages referencing disable-ccache.conf in the /etc/portage/package.env file.

Usage examples

Use different `MAKEOPTS` for a specific package

As mentioned at MAKEOPTS, a good rule of thumb is to set the amount of make(1) jobs to the minimum of the size of RAM divided by 2GB and CPU thread count. For most packages, each job uses less than 2 GB of RAM, so this is fine. However, some packages may need more RAM when compiling, which necessitates a lower --jobs value. This can be set using /etc/portage/package.env.

First, a file that appends the desired --jobs value to MAKEOPTS should be created:

FILE /etc/portage/env/makeopts-jobs-28.conf

MAKEOPTS="${MAKEOPTS} --jobs=28"

If MAKEOPTS contains multiple values for --jobs, the last one will be used by make.

This file can then be applied to packages that fail to compile with higher job counts:

FILE /etc/portage/package.env

dev-qt/qtwebengine makeopts-jobs-28.conf

Enable debug information for a specific package

Suppose a user would like to build GIMP with debug information because the user wants a development version and would like to report any crashes to GIMP upstream.

Create a file in /etc/portage/env that contains the desired changes:

FILE /etc/portage/env/debug.conf

CFLAGS="${CFLAGS} -g"
CXXFLAGS="${CXXFLAGS} -g"
FEATURES="splitdebug"

Next, add an entry to package.env followed by the name of the file created in the previous step:

FILE /etc/portage/package.env

media-gfx/gimp  debug.conf

Build certain packages in a different location

Suppose the Portage build directory is in tmpfs, but some packages are too large, and run out of space. The PORTAGE_TMPDIR can be modified to exclude the packages that are too large.

Create a file in /etc/portage/env that modifies PORTAGE_TMPDIR variable and sets it to an on-disk directory:

FILE /etc/portage/env/notmpfs.conf

PORTAGE_TMPDIR="/var/tmp/notmpfs"

Add large packages to package.env:

FILE /etc/portage/package.env

app-emulation/qemu-kvm  notmpfs.conf
app-office/libreoffice  notmpfs.conf debug.conf
www-client/firefox      notmpfs.conf

Do not forget to create the /var/tmp/notmpfs directory and change the ownership to the portage user and group.

Notice that it is possible to reference several files in /etc/portage/env for each package. (Tip originally blogged by Jeremy Olexa)

Amend an ebuild function

A package-specific file in the /etc/portage/env directory could help modifying an ebuild function, without creating a new ebuild repository. In this example, epatch_user is added to an old EAPI 5 ebuild:

FILE /etc/portage/env/media-gfx/fbida-2.12

src_prepare() { epatch_user || die; }

See also
See /etc/portage/bashrc for more information on what can be done in these files.

Caveats

emerge --info does not show changes from package.env

According to bug #41006, it is important to note that running emerge --info does not show changes from the package.env file. This may be fixed in a future Portage release.