Profile (Portage)

Resources

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

Structure

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 package masked by the profile using /etc/portage/package.unmask.
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.). Administrator settings in /etc/portage/make.conf and /etc/portage/package.use override profile settings in make.defaults.
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 in package.use.
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 settings from 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, unforcing or 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, with portage-2 added to the profile-format key in metadata/layout.conf, 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 'valid 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), e.g. amd64, arm, ppc64, etc. These are listed in the main repository's profiles/arch.list file.
The second one is a profile path name, 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/17.1/desktop/gnome/systemd from the main Gentoo repository. Profiles pathnames relative to the profiles subdirectory are shown so that the filesystem layout can be inferred, top-to-bottom ordering respects line ordering in relevant parent files.

default/linux/amd64/17.1/desktop/gnome/systemd  17 
 | L 
 +--> default/linux/amd64/17.1/desktop/gnome  15 
 |     | L 
 |     +--> default/linux/amd64/17.1/desktop  12 
 |     |     | L 
 |     |     +--> default/linux/amd64/17.1  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.1  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 profiles 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:

Profile	Notable settings	Relevant file(s)
base	Define most USE_EXPAND and profile variables, define 'base' system set packages, set `KERNEL`, `ELIBC` and `USERLAND` to `linux`, `glibc` and `GNU`, respectively	make.defaults, packages, use.force
default/linux	Add packages considered essential for Linux to the system set, set USE flags, set default value of `LDFLAGS`, unmask Linux-specific USE flags	make.defaults, packages, use.mask, package.use.mask
default/linux/amd64	Add profiles base and default/linux to the inheritance tree	parent
arch/base	Define the `ARCH` USE_EXPAND variable, mask USE flags only supported for some architectures	make.defaults, use.mask, package.use.mask
arch/amd64	Set `ARCH` to `amd64`, set `CHOST`, `ABI`, `MULTILIB_ABIS` and `DEFAULT_ABI` appropriately, set default values of `ACCEPT_KEYWORDS`, `CFLAGS`, `CXXFLAGS`, `FFLAGS` and `FCFLAGS`, define the `CPU_FLAGS_X86` USE_EXPAND variable, unmask USE flags supported for amd64	make.defaults, use.mask, package.use.mask
features/multilib	Unmask and unconditinally set the `multilib` USE flag	all
arch/amd64/lib32	Set `LIBDIR_x86` to `lib32`, and `SYMLINK_LIB` to `yes` to make {usr,}/lib a symlink to {usr,}/lib64	make.defaults
default/linux/amd64/17.1	Add profiles arch/amd64/lib32 and releases/17.1 to the inheritance tree	parent
releases	Set USE flags	make.defaults
releases/17.1	See here	package.mask, package.use.force
default/linux/amd64/17.1/desktop	Add profile targets/desktop to the inheritance tree	parent
targets/desktop	Set USE flags	make.defaults, package.use, package.use.force
default/linux/amd64/17.1/desktop/gnome	Add profile targets/desktop/gnome to the inheritance tree	parent
targets/desktop/gnome	Set USE flags; in particular, globally set `gnome`	make.defaults, package.use
default/linux/amd64/17.1/desktop/gnome/systemd	Add profile targets/systemd to the inheritance tree	parent
targets/systemd	Globally set `systemd` and `udev` USE flags, mask sys-fs/udev and eudev	make.defaults, package.mask, package.use.force

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, custom profiles not available in the main Gentoo repository as part of creating a custom ebuild repository. They can refer to profiles from the main repository in their parent file using the 'gentoo:' prefix, to avoid recreating all profile definitions, provided that the profile-formats key in metadata/layout.conf of the repository contains portage-2, as shown below.

Following is an example of a custom profile created in a local ebuild repository named 'local'. 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. It is also assumed to contain a package dev-libs/test-package that installs libraries:

FILE /etc/portage/repos.conf/local.conf

<syntaxhighlight lang="ini">[local]
# 'eselect repository' default location
location = /var/db/repos/local</syntaxhighlight>

FILE /var/db/repos/local/profiles/repo_name

local

FILE /var/db/repos/local/metadata/layout.conf

<syntaxhighlight lang="ini"># Slave repository rather than stand-alone
masters = gentoo
profile-formats = portage-2</syntaxhighlight>

user $ls -ld /var/db/repos/local

drwxr-xr-x 4 user user 4096 Dec 15 11:50 /var/db/repos/local

user $equery uses test-package

[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset
 * Found these USE flags for dev-libs/test-package-1
 U I
 - - abi_x86_32 : 32-bit (x86) libraries
 - - extras     : Builds the libprofile-test-extra library

A profile named custom will be created, which inherits settings from default/linux/amd64/17.1 in the main Gentoo repository, and two local profiles: 32bit, which sets the abi_x86_32 USE flag and unsets the extras USE flag by default for the package, and with-extras, which does exactly the opposite, to illustrate final settings determination.

Important
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 the 32bit and with-extras directories in the repository's profiles subdirectory:

user $cd /var/db/repos/local/profiles

user $mkdir 32bit && echo 7 >32bit/eapi &&

> echo dev-libs/test-package abi_x86_32 -extras >32bit/package.use

user $mkdir with-extras && echo 7 >with-extras/eapi &&

> echo dev-libs/test-package -abi_x86_32 extras >with-extras/package.use

Then, create the custom directory:

user $profile_name=custom

user $mkdir $profile_name && echo 7 >$profile_name/eapi &&

> cat <<EOF >$profile_name/parent
> gentoo:default/linux/amd64/17.1
> ../with-extras
> ../32bit
> EOF

Finally, 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

Available profile symlink targets:
  ...
  [46]  local:custom (dev)

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

root #eselect profile set 46

Let's check:

user $eselect profile show

Current /etc/portage/make.profile symlink:
  local:custom

user $ls -l /etc/portage/make.profile

lrwxrwxrwx 1 root root 40 Dec 15 12:00 /etc/portage/make.profile -> ../../var/db/repos/local/profiles/custom

This shows that eselect profile set updated the /etc/portage/make.profile symbolic link. In the general case, it would be necessary to run a world rebuild to apply the new settings to all packages, but checking first to make sure that the desired changes are going into effect with --ask:

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

However, for this example, knowing that the profile settings only affect dev-libs/test-package and assuming that the previously chosen profile was default/linux/amd64/17.1, only that package's reinstallation will be done.

user $equery uses test-package

[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset
 * Found these USE flags for dev-libs/test-package-1:
 U I
 + - abi_x86_32 : 32-bit (x86) libraries
 - - extras     : Builds the libprofile-test-extra library

This shows that because profile 32bit comes last in file custom/parent, its setting override those in profile with-extras, and the 32-bit version of the package's libraries is built.

FILE test-package-1/MakefilePackage's makefile snippet

<syntaxhighlight lang="make">%.so: %.c
   @echo Building $@ for architecture $$ARCH and ABI $$ABI "(CHOST=$$CHOST)"
   $(CC) -shared -fPIC -Wl,-soname=$@.1 $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -o $@ $< $(LDLIBS)</syntaxhighlight>

FILE /var/db/repos/local/dev-libs/test-package/test-package-1.ebuildEbuild snippet

<syntaxhighlight lang="bash">EAPI=7

inherit toolchain-funcs multilib-build multilib-minimal

# ...

IUSE="extras" # abi_x86_32 comes from an eclass

# ...

multilib_src_compile() {
   tc-export CC
   emake extras=$(usex extras)
}</syntaxhighlight>

root #ACCEPT_KEYWORDS="~amd64" emerge --oneshot test-package

Calculating dependencies  ... done!

>>> Verifying ebuild manifests

>>> Emerging (1 of 1) dev-libs/test-package-1::local
 * test-package-1.tar.gz BLAKE2B SHA512 size ;-) ...                     [ ok ]
>>> Unpacking source...
>>> Unpacking test-package-1.tar.gz to /var/tmp/portage/dev-libs/test-package-1/work
>>> Source unpacked in /var/tmp/portage/dev-libs/test-package-1/work
>>> Preparing source in /var/tmp/portage/dev-libs/test-package-1/work/test-package-1 ...
 * Will copy sources from /var/tmp/portage/dev-libs/test-package-1/work/test-package-1
 * abi_x86_32.x86: copying to /var/tmp/portage/dev-libs/test-package-1/work/test-package-1-abi_x86_32.x86
 * abi_x86_64.amd64: copying to /var/tmp/portage/dev-libs/test-package-1/work/test-package-1-abi_x86_64.amd64
>>> Source prepared.
>>> Configuring source in /var/tmp/portage/dev-libs/test-package-1/work/test-package-1 ...
 * abi_x86_32.x86: running multilib-minimal_abi_src_configure
 * abi_x86_64.amd64: running multilib-minimal_abi_src_configure
>>> Source configured.
>>> Compiling source in /var/tmp/portage/dev-libs/test-package-1/work/test-package-1 ...
 * abi_x86_32.x86: running multilib-minimal_abi_src_compile
make extras=no

Building libprofile-test.so for architecture amd64 and ABI x86 (CHOST=i686-pc-linux-gnu)

x86_64-pc-linux-gnu-gcc -m32 -shared -fPIC -Wl,-soname=libprofile-test.so.1  -O2 -pipe -Wl,-O1 -Wl,--as-needed -o libprofile-test.so libprofile-test.c
 * abi_x86_64.amd64: running multilib-minimal_abi_src_compile
make extras=no

Building libprofile-test.so for architecture amd64 and ABI amd64 (CHOST=x86_64-pc-linux-gnu)

x86_64-pc-linux-gnu-gcc -shared -fPIC -Wl,-soname=libprofile-test.so.1  -O2 -pipe -Wl,-O1 -Wl,--as-needed -o libprofile-test.so libprofile-test.c
>>> Source compiled.
>>> Test phase [not enabled]: dev-libs/test-package-1

>>> Install test-package-1 into /var/tmp/portage/dev-libs/test-package-1/image/ category dev-libs
 * abi_x86_32.x86: running multilib-minimal_abi_src_install
make DESTDIR=/var/tmp/portage/dev-libs/test-package-1/image/ libdir=/usr/lib32 extras=no install

Installing: libprofile-test.so

 * abi_x86_64.amd64: running multilib-minimal_abi_src_install
make DESTDIR=/var/tmp/portage/dev-libs/test-package-1/image/ libdir=/usr/lib64 extras=no install

Installing: libprofile-test.so

>>> Completed installing test-package-1 into /var/tmp/portage/dev-libs/test-package-1/image/

 * Final size of build directory: 68 KiB
 * Final size of installed tree:  32 KiB

strip: x86_64-pc-linux-gnu-strip --strip-unneeded -R .comment -R .GCC.command.line -R .note.gnu.gold-version
   usr/lib32/libprofile-test.so.1
   usr/lib64/libprofile-test.so.1

>>> Installing (1 of 1) dev-libs/test-package-1::local
>>> Auto-cleaning packages...

>>> No outdated packages were found on your system.

 * GNU info directory index is up-to-date.

Messages printed by the package's makefile (informational ones highlighted) show variables ARCH, CHOST_x86, CFLAGS_x86 (which adds GCC's -m32 option for 32-bit builds) and LDFLAGS, set by profile default/linux/amd64/17.1, are being inherited and are available in the ebuild's environment.

Now let's see what happens if line order is changed in custom/parent:

user $cat <<EOF >$profile_name/parent

> gentoo:default/linux/amd64/17.1
> ../32bit
> ../with-extras
> EOF

user $equery uses test-package

[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset
* Found these USE flags for dev-libs/test-package-1:
 U I
 - + abi_x86_32 : 32-bit (x86) libraries
 + - extras     : Builds the libprofile-test-extra library

This shows that because it now comes last in file custom/parent, settings in profile with-extras override those in profile 32bit, and, on a reinstallation, the 32-bit version of the package's libraries would be removed, and library libprofile-test-extra would be built:

root #ACCEPT_KEYWORDS="~amd64" emerge --oneshot test-package

Calculating dependencies  ... done!

>>> Verifying ebuild manifests

>>> Emerging (1 of 1) dev-libs/test-package-1::local
 * test-package-1.tar.gz BLAKE2B SHA512 size ;-) ...                     [ ok ]
>>> Unpacking source...
>>> Unpacking test-package-1.tar.gz to /var/tmp/portage/dev-libs/test-package-1/work
>>> Source unpacked in /var/tmp/portage/dev-libs/test-package-1/work
>>> Preparing source in /var/tmp/portage/dev-libs/test-package-1/work/test-package-1 ...
 * Will copy sources from /var/tmp/portage/dev-libs/test-package-1/work/test-package-1
 * abi_x86_64.amd64: copying to /var/tmp/portage/dev-libs/test-package-1/work/test-package-1-abi_x86_64.amd64
>>> Source prepared.
>>> Configuring source in /var/tmp/portage/dev-libs/test-package-1/work/test-package-1 ...
 * abi_x86_64.amd64: running multilib-minimal_abi_src_configure
>>> Source configured.
>>> Compiling source in /var/tmp/portage/dev-libs/test-package-1/work/test-package-1 ...
 * abi_x86_64.amd64: running multilib-minimal_abi_src_compile
make extras=yes

Building libprofile-test.so for architecture amd64 and ABI amd64 (CHOST=x86_64-pc-linux-gnu)

x86_64-pc-linux-gnu-gcc -shared -fPIC -Wl,-soname=libprofile-test.so.1  -O2 -pipe -Wl,-O1 -Wl,--as-needed -o libprofile-test.so libprofile-test.c

Building libprofile-test-extra.so for architecture amd64 and ABI amd64 (CHOST=x86_64-pc-linux-gnu)

x86_64-pc-linux-gnu-gcc -shared -fPIC -Wl,-soname=libprofile-test-extra.so.1  -O2 -pipe -Wl,-O1 -Wl,--as-needed -o libprofile-test-extra.so libprofile-test-extra.c
>>> Source compiled.
>>> Test phase [not enabled]: dev-libs/test-package-1

>>> Install test-package-1 into /var/tmp/portage/dev-libs/test-package-1/image/ category dev-libs
 * abi_x86_64.amd64: running multilib-minimal_abi_src_install
make DESTDIR=/var/tmp/portage/dev-libs/test-package-1/image/ libdir=/usr/lib64 extras=yes install

Installing: libprofile-test.so libprofile-test-extra.so

>>> Completed installing test-package-1 into /var/tmp/portage/dev-libs/test-package-1/image/

 * Final size of build directory: 52 KiB
 * Final size of installed tree:  28 KiB

strip: x86_64-pc-linux-gnu-strip --strip-unneeded -R .comment -R .GCC.command.line -R .note.gnu.gold-version
   usr/lib64/libprofile-test.so.1
   usr/lib64/libprofile-test-extra.so.1

>>> Installing (1 of 1) dev-libs/test-package-1::local
>>> Auto-cleaning packages...

>>> No outdated packages were found on your system.

 * GNU info directory index is up-to-date.

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.
gentoo-dev mailing list thread "amd64 17.1 profiles are now stable", May 19, 2019.
News item, "amd64 17.1 profiles are now stable", June 05, 2019. Retrieved on June 05, 2019.
profiles: Finally deprecate amd64 17.0 profiles
Bug 506276 — (no-symlink-lib) - kill SYMLINK_LIB=yes support.
Gentoo Forums thread "New profiles 17.1".

This article is issued from Gentoo. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.

Profile (Portage)

Structure

Combining profiles

Creating custom profiles

See also

External resources