Discover the features Portage has, such as support for distributed compiling,
ccache and more.
62012-06-29Portage Features

Portage has several additional features that makes your 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 you need to edit
/etc/make.conf's FEATURES variable which contains the
various feature keywords, separated by white space. In several cases you
will also need 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 make.conf man page:

$ man make.conf

To find out what FEATURES are default set, run emerge --info and search
for the FEATURES variable or grep it out:

$ emerge --info | grep FEATURES

Distributed CompilingUsing distcc

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.

You can find more information about distcc (and how to have it work
with Gentoo) in our Gentoo Distcc
Documentation.

Installing distcc

Distcc ships with a graphical monitor to monitor tasks that your computer is
sending away for compilation. If you use Gnome then put 'gnome' in your USE
variable. However, if you don't use Gnome and would still like to have the
monitor then you should put 'gtk' in your USE variable.

# emerge distcc

Activating Portage Support

Add distcc to the FEATURES variable inside /etc/make.conf.
Next, edit the MAKEOPTS variable to your liking. A known guideline is to fill in
"-jX" with X the number of CPUs that run distccd (including the current
host) plus one, but you might have better results with other numbers.

Now run distcc-config and enter the list of available distcc servers. For
a simple example we 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):

ccache is a fast compiler cache. When you compile a program, it will
cache intermediate results so that, whenever you recompile the same program, the
compilation time is greatly reduced. The first time you run ccache, it will be
much slower than a normal compilation. Subsequent recompiles should be faster.
ccache is only helpful if you will be recompiling the same application many
times; thus it's mostly only useful for software developers.

If you are interested in the ins and outs of ccache, please visit the
ccache homepage.

ccache is known to cause numerous compilation failures. Sometimes ccache
will retain stale code objects or corrupted files, which can lead to packages
that cannot be emerged. If this happens (if you receive errors like "File not
recognized: File truncated"), try recompiling the application with ccache
disabled (FEATURES="-ccache" in /etc/make.conf)
before reporting a bug. Unless you are doing development work, do not
enable ccache.
Installing ccache

To install ccache, run emerge ccache:

# emerge ccache

Activating Portage Support

Open /etc/make.conf and add ccache to the FEATURES variable.
Next, add a new variable called CCACHE_SIZE and set it to "2G":

CCACHE_SIZE="2G"

To check if ccache functions, ask ccache to provide you with its statistics.
Because Portage uses a different ccache home directory, you need to set the
CCACHE_DIR variable as well:

# CCACHE_DIR="/var/tmp/ccache" ccache -s

The /var/tmp/ccache location is Portage' default ccache home
directory; if you want to alter this setting you can set the CCACHE_DIR
variable in /etc/make.conf.

However, if you would run ccache, it would use the default location of
${HOME}/.ccache, which is why you needed to set the
CCACHE_DIR variable when asking for the (Portage) ccache statistics.

Using ccache for non-Portage C Compiling

If you would like to use ccache for non-Portage compilations, add
/usr/lib/ccache/bin to the beginning of your PATH variable (before
/usr/bin). This can be accomplished by editing
.bash_profile in your user's home directory. Using
.bash_profile is one way to define PATH variables.

PATH="/usr/lib/ccache/bin:/opt/bin:${PATH}"

Binary Package SupportCreating Prebuilt Packages

Portage supports the installation of prebuilt packages. Even though Gentoo does
not provide prebuilt packages by itself (except for the GRP snapshots) Portage
can be made fully aware of prebuilt packages.

To create a prebuilt package you can use quickpkg if the package is
already installed on your system, or emerge with the --buildpkg or
--buildpkgonly options.

If you want Portage to create prebuilt packages of every single package you
install, 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, you can create a central repository where
you store prebuilt packages. If you want to use this repository, you need 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:

PORTAGE_BINHOST="ftp://buildhost/gentoo"

When you want to install a prebuilt package, add the --getbinpkg option
to the emerge command alongside of the --usepkg 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:

# emerge --usepkg --getbinpkg gnumeric

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

$ man emerge

Fetching FilesParallel fetch

When you are emerging a series of packages, Portage can fetch the source files
for the next package in the list even while it is compiling another package,
thus shortening compile times. To make use of this capability, add
"parallel-fetch" to your FEATURES. Note that this is on by default, so you
shouldn't need to specifically enable it.

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 Portage Tree Snapshots

As an administrator, you can opt to only update your local Portage tree with a
cryptographically validated Portage tree snapshot as released by the Gentoo
infrastructure. This ensures that no rogue rsync mirror is adding unwanted code
or packages in the tree you are downloading.

To configure Portage, first create a truststore in which you download and accept
the keys of the Gentoo Infrastructure responsible for signing the Portage tree
snapshots. Of course, if you want to, you can validate this GPG key as per the
proper guidelines
(like checking the key fingerprint). You can find the list of GPG keys used by
the release engineering team on their project page.

Next, edit /etc/make.conf 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.

FEATURES="webrsync-gpg"
PORTAGE_GPG_DIR="/etc/portage/gpg"
SYNC=""

That's it. Next time you run emerge-webrsync, only the snapshots with
a valid signature will be expanded on your file system.