3.5 Files and directories

Portage files

Configuration directives

Portage comes with a default configuration stored in /etc/make.globals. When you take a look at it, you will 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/make.profile symlink. Portage' configurations are set in the make.defaults files of your profile and all parent profiles. We will explain more about profiles and the /etc/make.profile directory later on.

If you are planning on changing a configuration variable, do not alter /etc/make.globals or 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 this file.

You can also define a Portage configuration variable as an environment variable, but we do not recommend this.

Profile specific configuration

We have already encountered the /etc/make.profile directory. In fact, thi is not 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 do not work (or are masked-out) for that profile, etc.

User specific configuration

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.

You can create the following files within /etc/portage:

  • the package.mask directory, where you can create files listing the packages you never want Portage to install;
  • the package.unmask directory, where you can create files listing the packages you want to be able to install even though the Gentoo developers highly discourage you from emerging them;
  • the package.keywords directory, where you can create files listing the packages you want to be able to install even though the package has not been found suitable for your system or architecture (yet);
  • the package.use directory, where you can create files listing the packages which specify the USE flags you want to use for certain packages without having the entire system use them.

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, see man portage.

Changing Portage file and 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 your filesystem.

This document is not meant to be used as a reference though. If you need full coverage, please consult the Portage and make.conf man pages (man portage and man make.conf, respectively).

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), do not 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 these variables: PKGDIR, DISTDIR, RPMDIR.

Binary packages

Even though Portage does not 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 /var/calculate/remote/packages. This location is defined by the @PKGDIR variable.

Source code

Application source code is stored in /var/calculate/remote/distfiles by default. This location is defined by the DISTDIR variable.

RPM files

Although Portage cannot use RPM files, they can be created with the ebuild command (please see using ebuild). By default, Portage stores RPM files in /usr/portage/rpm, as defined by the RPMDIR variable.

Portage database

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.

Portage cache

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.

Building software

Temporary Portage files

Portage's temporary files are stored in /var/tmp by default. This is defined by the PORTAGE_TMPDI 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 the BUILD_PREFIX variable.

Building directory

Portage creates specific build directories for each package it emerges inside /var/tmp/portage. This location is defined by the BUILD_PREFIX variable.

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.

Logging features

Ebuild logging

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.

Thank you!