Handbook:Parts/Working/Features

Portage features
Portage has several additional features that makes the Gentoo experience even better. Many of these features rely on certain software tools that improve performance, reliability, security, ...

To enable or disable certain Portage features, edit and update or set the   variable which contains the various feature keywords, separated by white space. In several cases it will also be necessary to install the additional tool on which the feature relies.

Not all features that Portage supports are listed here. For a full overview, please consult the man page:

To find out what  are set by default, run  and search for the   variable or  it out:

Using distcc
is a program to distribute compilations across several, not necessarily identical, machines on a network. The distcc client sends all necessary information to the available distcc servers (running distccd) so they can compile pieces of source code for the client. The net result is a faster compilation time.

More information about distcc (and how to have it work with Gentoo) can be found in the Distcc article.

Installing distcc
Distcc ships with a graphical monitor to monitor tasks that the computer is sending away for compilation. This tool is automatically installed if USE=gnome or USE=gtk is set.

Activating portage distcc support
Add distcc to the FEATURES variable inside. Next, edit the MAKEOPTS variable and increase the number of parallel build jobs that the system allows. A known guideline is to fill in "-jX" with X the number of CPUs that run distccd (including the current host) plus one, but that is just a guideline.

Now run  and enter the list of available distcc servers. For a simple example assume that the available DistCC servers are 192.168.1.102 (the current host), 192.168.1.103 and 192.168.1.104 (two "remote" hosts):

Don't forget to run the distccd daemon as well:

About ccache
is a fast compiler cache. Whenever an application is compiled, it will cache intermediate results so that, whenever the same program is recompiled, the compilation time is greatly reduced. The first time ccache is run, it will be much slower than a normal compilation. Subsequent recompiles however should be faster. ccache is only helpful if the same application will be recompiled many times (or upgrades of the same application are happening frequently); thus it's mostly only useful for software developers.

For more information about ccache, please visit its homepage.

Installing ccache
To install ccache, run :

Activating portage ccache support
Open and add ccache to the FEATURES variable. Next, add a new variable called CCACHE_SIZE and set it to "2G":

To check if ccache functions, ask ccache to provide its statistics. Because Portage uses a different ccache home directory, it is necessary to temporarily set the CCACHE_DIR variable:

The location is Portage' default ccache home directory; it can be changed by setting the CCACHE_DIR variable in.

When running  standalone, it would use the default location of, which is why the CCACHE_DIR variable needs to be set when asking for the (Portage) ccache statistics.

Using ccache outside portage
To use ccache for non-Portage compilations, add to the beginning of the PATH variable (before ). This can be accomplished by editing in the user's home directory. Using is one way to define PATH variables.

Creating prebuilt packages
Portage supports the installation of prebuilt packages. Even though Gentoo does not provide prebuilt packages by itself Portage can be made fully aware of prebuilt packages.

To create a prebuilt package use  if the package is already installed on the system, or emerge with the   or   options.

To have portage create prebuilt packages of every single package that gets installed, add buildpkg to the FEATURES variable.

More extended support for creating prebuilt package sets can be obtained with catalyst. For more information on catalyst please read the Catalyst Frequently Asked Questions.

Installing prebuilt packages
Although Gentoo doesn't provide one, it is possible to create a central repository where prebuilt packages are stored. In order to use this repository, it is necessary to make Portage aware of it by having the PORTAGE_BINHOST variable point to it. For instance, if the prebuilt packages are on ftp://buildhost/gentoo:

To install a prebuilt package, add the  option to the emerge command alongside of the   option. The former tells emerge to download the prebuilt package from the previously defined server while the latter asks emerge to try to install the prebuilt package first before fetching the sources and compiling it.

For instance, to install gnumeric with prebuilt packages:

More information about emerge's prebuilt package options can be found in the emerge man page:

Distributing prebuilt packages to others
If prebuilt packages are to be distributed to others, then make sure that this is permitted. Check the distribution terms of the upstream package for this. For example, for a package released under the GNU GPL, sources must be made available along with the binaries.

Ebuilds may define a  restriction in their   variable if built binaries are not distributable. Sometimes this restriction is conditional on one or more USE flags.

By default, Portage will not mask any packages because of restrictions. This can be changed globally by setting the  variable in. For example, to mask packages that have a  restriction, add the following line to :

It is also possible to override the  variable by passing the   option to the   command. For example,  will temporarily mask packages with a   restriction.

Also consider setting the  variable when distributing packages. See the Licenses section for this.

Userfetch
When Portage is run as root, FEATURES="userfetch" will allow Portage to drop root privileges while fetching package sources. This is a small security improvement.

Pulling validated Gentoo ebuild tree snapshots
Administrators can opt to update the local Gentoo ebuild tree with a cryptographically validated tree snapshot as released by the Gentoo infrastructure. This ensures that no rogue rsync mirror is adding unwanted code or packages to the tree the system is downloading.

The Gentoo release media OpenPGP keys are now available as a binary keyring, installed via the package.

This will install the keyring to the location.

Make sure that package is installed:

Use gpg to verify that the keys in the keyring are the correct keys:

Verify the fingerprints of the key(s) against those listed here: Project:RelEng Repeat the following command for each key you wish to trust. (Substitute the keyid '0x...' for the desired key you wish to trust.)

The system is now set-up to sync using only OpenPGP/gpg verified snapshots. Several command options are available to perform the sync.

Original install and configuration instructions

To configure Portage to validate the snapshots, first create a truststore in which the keys of the Gentoo Infrastructure responsible for signing the Portage tree snapshots are stored. Of course, this OpenPGP key can be validated as per the proper guidelines (like checking the key fingerprint). The list of OpenPGP keys used by the release engineering team is available on their project page.

Make sure that is installed:

In the next set of commands, substitute the keys with those mentioned on the release engineering site:

Next, edit and enable support for validating the signed portage tree snapshots (using FEATURES="webrsync-gpg") and disabling updating the Portage tree using the regular emerge --sync method.

In the file, clear the   and   variables so that emerge --sync no longer works (and thus no longer pulls in ebuilds that come from a potentially non-validated source):

That is it. Next time emerge-webrsync is ran, only the snapshots with a valid signature will be expanded on the filesystem.