Files and directories

Updated 4 July 2019

Portage files

Configuration directives

By default, Portage settings are stored in /etc/portage/make.conf/custom. If you open this file, you will see that all of them are variables. Each variable will be explained later.

As many directives are architecture-specific, Portage comes with default settings included in your profile. The /etc/portage/make.profile symlink points to your profile. Portage can be configured via the make.defaults files of your profile and those of all parent profiles. We will talk more about profiles and /etc/portage/make.profile later on.

You will also find the /etc/portage/make.conf/binhost file, where cl-update stores the settings of the binary package repo, as well as /etc/portage/make.conf/0-base, where the descriptions of the overlays enabled with layman are imported to.

Portage variables can also be used as environment variables, but we do not recommend it.

Profile-specific configuration

Do you remember the /etc/portage/make.profile directory? In fact, this is not a directory, but a symbolic link to a profile, by default the one contained in /var/lib/layman/calculate/profiles. However, you can create your own profiles anywhere, provided you specify the links to them. The profile the link points to is your system's profile.

A profile contains architecture-specific information for Portage, such as the list of packages in the system, the list of broken (or masked) packages, etc.

User-specific configuration

If you need to change Portage's behavior regarding software installation, you will need to edit files in /etc/portage. We strongly recommend editing files from /etc/portage to reconfigure Portage. Please do not attempt doing it using environment variables.

The subdirectories available in /etc/portage are:

  • +package.mask stores files listing packages that Portage should never install;
  • +package.unmask stores files listing the packages you want to be able to install, even if the Gentoo developers do not recommend it;
  • +package.keywords, that stores the files listing packages available for installation, even though they are not recommended for your system or architecture (yet);
  • +package.use, that stores the files listing package-specific USE values, instead of global ones.

For more information about the /etc/portage directory, as well as the files you can create there, see the Portage man page man portage.

Editing Portage files and modifying locations

The above-mentioned configuration files may not be stored anywhere else, as Portage always searches for its configuration files where they belong. Yet Portage also uses quite a few other directories for various purposes: compilation, source code storage, Portage tree storage, etc.

There are default directories that can be modified to your liking by editing /etc/make.conf. The rest of this chapter is about the dedicated locations Portage uses for its purposes, and how to modify them.

Note that this manual does not reproduce the official documentation. If you need full info, please refer to Portage and make.conf man pages (man portage and man make.conf respectively).

File storage

Portage tree

By default, the Portage tree is stored in /usr/portage. This is defined by the PORTDIR value. If you store the Portage tree somewhere else (by editing this variable), remember to modify the symlink, /etc/portage/make.profile accordingly.

If you edit PORTDIR, you may also need to edit the following variables: PKGDIR, DISTDIR, RPMDIR since they do not register any PORTDIR+ modifications. It has to do with how Portage handles them.

Binary packages

Though Portage does not use precompiled packages by default, they are well supported. If you tell Portage to work with precompiled packages, it will look for them in /var/calculate/remote/packages. This location is defined by the PKGDIR variable.

Source code

By default, all source code is saved in /var/calculate/remote/distfiles. This location is defined by the DISTDIR variable.

RPM files

Even though Portage cannot use RPM files, it can still create them via the ebuild command (see Working with ebuild). By default, Portage stores RPM files in the /usr/portage/rpm directory, as defined by RPMDIR.

Portage database

Portage keeps track of the state of your system (packages installed, files relating to specific packages, etc.) in /var/db/pkg. Do not edit those files manually! It could disorient Portage completely.

Portage cache

The Portage cache (including last modification time, virtual packages, dependency data, etc.) is stored in /var/cache/edb. This location is indeed a cache: you can clear it at any time when Portage-related utilities are not running.

Software compilation

Portage temporary files

By default, Portage stores temporary files in /var/tmp. This behaviour is defined by the PORTAGE_TMPDIR variable.

If you edit the PORTAGE_TMPDIR value, you may have to modify BUILD_PREFIX accordingly, since it does not see PORTAGE_TMPDIR modifications. This is due to how it is processed by Portage.

Compilation directory

Portage creates package-specific build directories in /var/tmp/portage. It is defined by the BUILD_PREFIX value.

Locating the live filesystem

By default, Portage installs all files in the current file system (/), but this can be modified by editing the ROOT environment variable. It can be useful when creating a customized ISO.

Logging

Ebuild log

Portage can create ebuild-specific log files, but only if PORT_LOGDIR provides a location where Portage (user 'portage') is allowed to write to. This variable is not set by default.