Profile (Portage)

From Gentoo Wiki
(Redirected from Profile)
Jump to: navigation, search
Resources

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.

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.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.). 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, 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.0/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.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 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.0 Add profiles arch/amd64/lib32 and releases/17.0 to the inheritance tree parent
releases Set USE flags make.defaults
releases/17.0 See here package.mask, package.use.force
default/linux/amd64/17.0/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.0/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.0/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 repository. They can refer to profiles from the main repository in their parent file using the 'gentoo:' prefix, to avoid recreating all profile definitions.

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
[local]
# 'eselect repository' default location
location = /var/db/repos/local
FILE /var/db/repos/local/profiles/repo_name
local
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
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.0 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.0
> ../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.0, 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
%.so: %.c
   @echo Building $@ for architecture $$ARCH and ABI $$ABI "(CHOST=$$CHOST)"
   $(CC) -shared -fPIC -Wl,-soname=$@.1 $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -o $@ $< $(LDLIBS)
FILE /var/db/repos/local/dev-libs/test-package/test-package-1.ebuildEbuild snippet
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)
}
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.0, 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.0
> ../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.

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