Profile (Portage)

From Gentoo Wiki
Jump to: navigation, search

A Portage profile specifies default state (set or unset) of global and per-package USE flags, default values for most variables found in /etc/portage/make.conf, and defines a set of system packages. It can also force USE flags to be unconditionally set or unset, either globally, for the architecture's stable branch or per package, and mask packages or specific versions of them. Profile structure and function is specified by the Package Manager Specification (PMS).

Profiles are defined on an ebuild repository basis; the ones from the main repository are maintained by the Gentoo developers, but users can define their own.

The profile module of the eselect tool allows users to switch profiles, and during Gentoo's installation process, a profile must be selected as described in section "Choosing the right profile" of the Gentoo handbook.


Profiles are defined in directories contained in the profiles subdirectory of an ebuild repository, which also contains the mandatory repo_name file that specifies the name of the repository. These are some of the files that can be present in a directory that defines a profile:

  • eapi, which specifies the EAPI to use when handling the directory in question.
  • packages, which specifies packages that are members of the system set.
  • package.mask, which specifies masked packages. The administrator can unmask a profile-masked package using /etc/portage/package.mask.
  • make.defaults, with make.conf-like variable assignments, including USE flag global default state (set or unset) and profile variables with special meaning (like ARCH, USE_EXPAND, CONFIG_PROTECT, IUSE_IMPLICIT, etc.).
  • package.use, which defines default USE flag state on a per package basis. Administrator settings in /etc/portage/make.conf and /etc/portage/package.use override profile settings.
  • use.force and use.mask, which unconditionally set or unset USE flags, overriding administrator settings in /etc/portage/make.conf and /etc/portage/package.use. If a flag is both masked and forced, the mask takes precedence.
  • package.use.force and package.use.mask, which unconditionally set or unset USE flags on a per package basis, overriding administrator settings in /etc/portage/make.conf and /etc/portage/package.use, and profile settings in use.force and use.mask.
  • use.stable.force, use.stable.mask, package.use.stable.force and package.use.stable.mask, which work like use.force, use.mask, package.use.force and package.use.mask, but override them for packages in the stable branch of the current architecture.

USE flag settings in profile use.* and package.use.* files can be overridden by the administrator with files of the same name in directory /etc/portage/profile. For complete information about profile directory structure please consult the PMS. A summary is also contained in the Devmanual and man portage.

Combining profiles

Profile settings can be combined in a cascading/stacking fashion, by including a file named parent in the directory that defines the profile. This makes the profile inherit the settings in other profiles, which can be partially overriden. For example, by unsetting a USE flag by default that is set by default in a parent profile and vice-versa, inverting its forced state, unmasking packages masked in a parent profile, adding or removing additional packages to/from the system set, etc. parent must contain a list of profile pathnames, relative to the directory that contains the file. As an extension, Portage also allows prepending an installed repository name (as specified in /etc/portage/repos.conf) followed by a colon (':') to a profile pathname, which is then interpreted relative to the profiles subdirectory of the named repository.

Because parent profiles can also contain a parent file, an inheritance tree is produced as a result. The Package Manager Specification specifies how settings in each file of a profile directory (i.e. packages, make.defaults, package.use.force and package.use.mask, etc.) combine. In particular, it defines an ordering of parent profiles to determine the final settings: the inheritance tree is traversed depth-first, left-to-right, with multiple occurrences of the same profile processed repeatedly. The left-to-right order is defined by line order in parent files.

The PMS uniformly calls 'profile' all directories with suitable structure that are contained in an ebuild repository's profiles subdirectory. A subset designated as 'available for use' must be listed in file profiles/profiles.desc, a text file that must contain lines with three fields separated by whitespace characters (space and TAB):

  • The first one is an architecture, in the format valid as the value of ARCH (and for setting KEYWORDS in ebuilds) as defined in the repository's profiles/arch.list file (e.g. amd64, arm, ppc64, etc.).
  • The second one is a profile pathname, relative to the profiles directory.
  • The third and last one is a 'stability indicator'. Gentoo's main repository, for instance, uses stable, dev and exp (experimental) for that field.

The eselect profile list command only shows profiles in profiles.desc files of all repositories configured in /etc/portage/repos.conf, with an architecture field that matches the machine's architecture. These are the ones that in most contexts are referred to as 'profiles' with no further qualification. Profiles not named in profiles.desc might be named in other profiles' parent files, and can be thought of as 'subprofiles' or 'profile building blocks'.

Following is an example that shows parent profiles and the inheritance tree for profile default/linux/amd64/13.0/desktop/kde in the main Gentoo repository:

CODE Stacked profiles example
|-- arch
|   |-- amd64 <--------------.
|   |   `-- parent >-------- | ----------------------.
|   -- base <--------------- | ----------------------|
|-- base <-------------------|                       |
|-- default                  |                       |
|   `-- linux <--------------|                       |
|       `-- amd64 <--------- | ------------------.   |
|           |-- parent >-----'                   |   |
|           `-- 13.0 <-----------------------.   |   |
|               |-- parent >---------------- | --|   |
|               `-- desktop <------------.   |   |   |
|                   |-- parent >-------- | --|   |   |
|                   `-- kde              |   |   |   |
|                       `-- parent >-----|   |   |   |
|-- features                             |   |   |   |
|   `-- multilib <-----------.           |   |   |   |
|       `-- lib32 <--------- | --------- | - | - | --'
|           `-- parent >-----'           |   |   |
|-- releases <-----------.               |   |   |
|   `-- 13.0 <---------- | ------------- | - | --'
|       `-- parent >-----'               |   |
`-- targets                              |   |
    `-- desktop <----------------------- | --'
        `--kde <----------- | -----------'
           `-- parent >-----'

The following table gives a quick overview of files contained in each profile directory:

base default
releases releases
eapi Yes No No No No No Yes Yes Yes No No No Yes No No
make.defaults No Yes No Yes Yes No No No No Yes Yes Yes Yes Yes Yes
packages No No No Yes Yes No No No No No No No No No No No No No No Yes No No No No No No No No No No
package.mask Yes No No Yes No No No No No No No No Yes No No
package.use No No No Yes Yes No No No No No No No No Yes Yes
package.use.force No Yes No Yes No No No No No No No No No No No
package.use.mask No Yes No Yes Yes No No No No No No No No No No
profile.bashrc No No No Yes No No No No No No No No No No No
use.force No Yes No Yes No No No No No Yes No No No No Yes
use.mask No Yes Yes Yes No No No No No Yes No No No No No

For information about the exact way in which settings in the different profile files combine please consult the PMS.

Creating custom profiles

Users can create specialized profiles not available in the main Gentoo repository as part of creating a custom repository. They can refer to profiles from the main repository in their parent file using the 'gentoo:' prefix, to avoid recreating all profile definitions. The custom repository should be a slave of the main Gentoo repository (i.e. masters = gentoo) to avoid having to provide required files (like arch.list and others).

As example, a custom profile named plasma-hardened that combines default/linux/amd64/17.0/hardened (hardened Linux profile for architecture amd64, release 17.0) and default/linux/amd64/17.0/desktop/plasma/systemd (Linux desktop profile for architecture amd64, release 17.0, with systemd) from the main repository can be created in a local ebuild repository named 'local' as follows. The repository is assumed to be in /var/db/repos/local (i.e. the default location for eselect repository), world-readable and owned by a non-root user.

FILE /etc/portage/repos.conf/local.conf
# 'eselect repository' default location
location = /var/db/repos/local
FILE /var/db/repos/local/profiles/repo_name
FILE /var/db/repos/local/metadata/layout.conf
# Slave repository rather than stand-alone
masters = gentoo
profile-formats = portage-2
user $ls -ld /var/db/repos/local
drwxr-xr-x 4 user user 4096 Dec 15 11:50 /var/db/repos/local
Since the profile inheritance tree is traversed depth-first, left-to-right, the order in which profile pathnames are listed in parent files can dramatically affect the resulting settings, as left-to-right ordering is defined by it. If emerge yields resolution problems after switching to the custom profile, try changing the order of the lines. It may be impossible to get some combinations to work correctly; make sure you have read and understood the algorithm specified in the PMS!

First, create a plasma-hardened directory in the repository's profiles subdirectory:

user $profile_name=plasma-hardened
user $cd /var/db/repos/local/profiles && mkdir $profile_name && cat <<EOF >$profile_name/parent
> gentoo:default/linux/amd64/17.0/desktop/plasma/systemd
> gentoo:default/linux/amd64/17.0/hardened

Then, insert the newly created profile in the repository's profiles.desc file, giving it a dev 'stability indicator' for example:

user $echo `portageq envvar ARCH` $profile_name dev >profiles.desc

Verify that eselect profile list lists the new profile:

user $eselect profile list
 [38] local:plasma-hardened

Now it is possible to actually switch to the new profile using eselect profile set:

root #eselect profile set 38

Let's check:

user $eselect profile show
Current /etc/portage/make.profile symlink:
user $ls -l /etc/portage/make.profile
lrwxrwxrwx 1 root root 49 Dec 15 12:00 /etc/portage/make.profile -> ../../var/db/repos/local/profiles/plasma-hardened

This shows that eselect profile set updated the /etc/portage/make.profile symbolic link. Now it's possible to run a world rebuild to apply the new settings to all packages, but first check to make sure that the desired changes are going into effect with --ask:

root #emerge --ask --update --newuse --deep --complete-graph @world

See also

  • Package Manager Specification — a standardization effort to ensure that the ebuild file format, the ebuild repository format (of which the Gentoo ebuild repository is the main incarnation), as well as behavior of the package managers interacting with these ebuilds is properly agreed upon and documented.
  • Multilib layout for amd64 architecture.

External resources