Profile (Portage)

A Portage profile Article description::specifies default state (set or unset) of global and per-package [[USE flags, default values for most variables found in, 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  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.

Structure
Profiles are defined in directories contained in the subdirectory of an ebuild repository, which also contains the mandatory  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:


 * , which specifies the EAPI to use when handling the directory in question.
 * , which specifies packages that are members of the system set.
 * , which specifies masked packages. The administrator can unmask a profile-masked package using.
 * , with -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.).
 * , which defines default USE flag state on a per package basis. Administrator settings in and  override profile settings.
 * and, which unconditionally set or unset USE flags, overriding administrator settings in and . If a flag is both masked and forced, the mask takes precedence.
 * and, which unconditionally set or unset USE flags on a per package basis, overriding administrator settings in and , and profile settings in  and.
 * ,, and , which work like , ,  and , but override them for packages in the stable branch of the current architecture.

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

Combining profiles
Profile settings can be combined in a cascading/stacking fashion, by including a file named 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. 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 ) followed by a colon (':') to a profile pathname, which is then interpreted relative to the subdirectory of the named repository.

Because parent profiles can also contain a 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., , and , 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 files.

The PMS uniformly calls 'profile' all directories with suitable structure that are contained in an ebuild repository's subdirectory. A subset designated as 'available for use' must be listed in file, 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 file (e.g., , , etc.).
 * The second one is a profile path name, relative to the 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 command only shows profiles in  files of all repositories configured in, 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 might be named in other profiles'  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 from the main Gentoo repository. Profiles pathnames relative to the subdirectory are shown so that the filesystem layout can be inferred, top-to-bottom ordering respects line ordering in relevant  files. default/linux/amd64/17.0/desktop/gnome/systemd 17 | L +--> default/linux/amd64/17.0/desktop/gnome 15 |    | L |    +--> default/linux/amd64/17.0/desktop 12 |    |     | L |    |     +--> default/linux/amd64/17.0 10 |    |     |     | L |    |     |     +--> default/linux/amd64 3 |    |     |     |     | L |    |     |     |     +--> base 1 |    |     |     |     | R |    |     |     |     +--> default/linux 2 |    |     |     |  |     |     |     +--> arch/amd64/lib32 7 |    |     |     |     |  |     |     |     |     +--> arch/amd64 6 |    |     |     |           | L |    |     |     |           +--> arch/base 4 |    |     |     |           | R |    |     |     |           +--> features/multilib 5 |    |     |     | R |    |     |     +--> releases/17.0  9 |    |     |           |  |     |     |           +--> releases 8 |    |     | R |    |     +--> targets/desktop 11 |    | R |    +--> targets/desktop/gnome 14 |          |  |           +--> targets/desktop 13 | R +--> targets/systemd 16

The L and R markers indicate the leftmost and rightmost branches in the corresponding tree representation, and the numbers represent the order in which they are considered for computing the final settings. Profiles with larger numbers override settings in profiles with smaller numbers. The following table gives a quick overview of notable settings for each of the intervening profiles, as well as the relevant files that implement them:

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 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. ) to avoid having to provide required files (like  and others).

As example, a custom profile named that combines  (hardened Linux profile for architecture, release 17.0) and  (Linux desktop profile for architecture , 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 (i.e. the default location for ), world-readable and owned by a non-root user.

First, create a directory in the repository's  subdirectory:

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

Verify that lists the new profile:

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

Let's check:

This shows that updated the  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 :

External resources

 * News item, "Experimental amd64 17.1 profiles up for testing", December 26th, 2017. Retrieved on December 16th, 2018.
 * gentoo-dev mailing list thread "Developers, please start switching to 17.1 amd64 profiles", May 22nd, 2018.
 * — (no-symlink-lib) - kill SYMLINK_LIB = support.
 * Gentoo Forums thread "New profiles 17.1".