Handbook:Parts/Working/Features

Parts Handbook
Installation
About the installation
Choosing the media
Configuring the network
Preparing the disks
Installing stage3
Installing base system
Configuring the kernel
Configuring the system
Installing tools
Configuring the bootloader
Finalizing
Working with Gentoo
Portage introduction
USE flags
Portage features
Initscript system
Environment variables
Working with Portage
Files and directories
Variables
Mixing software branches
Additional tools
Custom package repository
Advanced features
Network configuration
Getting started
Advanced configuration
Modular networking
Wireless
Adding functionality
Dynamic management

Portage features

Portage has several additional features that make 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 /etc/portage/make.conf and update or set the FEATURES 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 make.conf man page:

user $man make.conf

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

user $emerge --info | grep ^FEATURES=

Distributed compiling

Using 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.

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.

root #emerge --ask sys-devel/distcc

Activating Portage distcc support

Add distcc to the FEATURES variable inside /etc/portage/make.conf. Next, edit the MAKEOPTS variable and increase the number of parallel build jobs that the system allows. A known guideline is to fill in -jN where N is the number of CPUs that run distccd (including the current host) plus one, but that is just a guideline.

Now run distcc-config 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):

root #distcc-config --set-hosts "192.168.1.102 192.168.1.103 192.168.1.104"

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

root #rc-update add distccd default

root #/etc/init.d/distccd start

Caching compilation objects

About ccache

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.

Warning
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 (errors like "File not recognized: File truncated" come up in build logs), try recompiling the application with ccache disabled (FEATURES="-ccache" in /etc/portage/make.conf) before reporting a bug.

Installing ccache

To install ccache run the following command:

root #emerge --ask dev-util/ccache

Activating Portage ccache support

Open /etc/portage/make.conf and add ccache to any values defined in the FEATURES variable. If FEATURES does not exist, then create it. Next, add a new variable called CCACHE_SIZE and set it to 2G:

FILE /etc/portage/make.confEnabling Portage ccache support

FEATURES="ccache"
CCACHE_SIZE="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:

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

The /var/tmp/ccache/ location is Portage' default ccache home directory; it can be changed by setting the CCACHE_DIR variable in /etc/portage/make.conf.

When running ccache standalone, it would use the default location of ${HOME}/.ccache/, 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 /usr/lib/ccache/bin/ to the beginning of the PATH variable (before /usr/bin). This can be accomplished by editing ~/.bash_profile in the user's home directory. Using ~/.bash_profile is one way to define PATH variables.

FILE ~/.bash_profileSetting the ccache location before any other PATH

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

Binary package support

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 the quickpkg command if the package is already installed on the system, or emerge with the --buildpkg or --buildpkgonly 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 FAQ.

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:

FILE /etc/portage/make.confAdd PORTAGE_BINHOST location

PORTAGE_BINHOST="ftp://buildhost/gentoo"

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:

root #emerge --usepkg --getbinpkg gnumeric

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

user $man emerge

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 bindist restriction in their RESTRICT 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 ACCEPT_RESTRICT variable in /etc/portage/make.conf. For example, to mask packages that have a bindist restriction, add the following line to make.conf:

FILE /etc/portage/make.confOnly accept binary distributable packages

ACCEPT_RESTRICT="* -bindist"

It is also possible to override the ACCEPT_RESTRICT variable by passing the --accept-restrict option to the emerge command. For example, --accept-restrict=-bindist will temporarily mask packages with a bindist restriction.

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

Important
It is entirely the responsibility of each user to comply with packages' license terms and with laws of each user's country. The metadata variables defined by ebuilds (RESTRICT or LICENSE) can provide guidance when distribution of binaries is not permitted, however output from Portage or questions answered by the Gentoo developers are not legal statements and should not be relied upon as such. Be cautious to abide by the law of your physical location.

Fetching files

Userfetch

Portage is normally run as the root user. Setting FEATURES="userfetch" will allow Portage to drop root privileges while fetching package sources and run with user/group permissions of portage:portage. This is a small security improvement.

If userfetch is set in FEATURES be sure to change the owner of all the files beneath /usr/portage using the chown command with root privileges:

root #chown --recursive --verbose portage:portage /usr/portage

Validated Gentoo repository snapshots

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

Note
The following is an updated method for setting up and using the emerge-webrsync sync method using repos.conf.

The Gentoo release media OpenPGP keys are now available as a binary keyring. These can be installed via the app-crypt/gentoo-keys package:

root #emerge --ask app-crypt/gentoo-keys

This will install the keyring to the /var/lib/gentoo/gkeys/keyrings/gentoo/release location.

FILE /etc/portage/make.confEnabling GPG support in Portage

FEATURES="webrsync-gpg"
PORTAGE_GPG_DIR="/var/lib/gentoo/gkeys/keyrings/gentoo/release"

FILE /etc/portage/repos.conf/gentoo.confClear the sync-uri variable

[DEFAULT]
main-repo = gentoo
 
[gentoo]
# Disable synchronization by clearing the values or setting auto-sync = no
# Do not set value of the variables in this configuration file using quotes ('' or "")!
# For portage-2.2.18 use 'websync'
# For portage-2.2.19 and greater use 'webrsync' (websync was renamed to webrsync)
sync-type = webrsync
sync-uri = 
auto-sync = yes

Make sure that app-crypt/gnupg package is installed:

root #emerge --ask app-crypt/gnupg

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

root #gpg --homedir /var/lib/gentoo/gkeys/keyrings/gentoo/release --with-fingerprint --list-keys --keyid-format 0xlong

Verify the fingerprints of the key(s) against those listed on the official Gentoo release engineering project page.

Important
If any of the keys installed from app-crypt/gentoo-keys should expire, run gkeys from app-crypt/gkeys to refresh them from the key server:

root #emerge --ask app-crypt/gkeys

root #gkeys refresh-key -C gentoo

Repeat the following command for each key you wish to trust. (Substitute the keyid '0x...' for the desired key you wish to trust.)

root #gpg --homedir /var/lib/gentoo/gkeys/keyrings/gentoo/release --edit-key 0xDB6B8C1F96D8BF6D trust

Should a GPG command-line menu appear, fully trust the key and quit the program by entering the following:

gpg>4

gpg>quit

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

Note
Only one of the following commands is needed to sync. See the Portage's sync wiki article for more details.

root #emerge --sync

root #emaint sync -a

root #emaint sync --repo gentoo

root #emerge-webrsync

Verify distfiles

To re-verify the integrity and (potentially) re-download previously removed/corrupted distfiles for all currently installed packages, run:

root #emerge --ask --fetchonly --emptytree @world

← Home →