Variables

There are a number of special variables which must be set in ebuilds, and many more which can optionally be specified. There are also some predefined variables which are of use throughout the ebuild.

Predefined Read-Only Variables

The following variables are defined for you. You must not attempt to set them. Developers must not rely on package manager specific values for these variables when writing ebuilds.

Variable Purpose
P Package name and version (excluding revision, if any), for example vim-6.3.
PN Package name, for example vim.
PV Package version (excluding revision, if any), for example 6.3. It should reflect the upstream versioning scheme.
PR Package revision, or r0 if no revision exists.
PVR Package version and revision (if any), for example 6.3, 6.3-r1.
PF Full package name, ${PN}-${PVR}, for example vim-6.3-r1.
A All the source files for the package (excluding those which are not available because of USE flags).
CATEGORY Package's category, for example app-editors.
FILESDIR Path to the ebuild's files/ directory, commonly used for small patches and files. For example: "${PORTDIR}/${CATEGORY}/${PN}/files".
WORKDIR Path to the ebuild's root build directory. For example: "${PORTAGE_BUILDDIR}/work".
T Path to a temporary directory which may be used by the ebuild. For example: "${PORTAGE_BUILDDIR}/temp".
D Path to the temporary install directory. For example: "${PORTAGE_BUILDDIR}/image".
HOME Path to a temporary directory for use by any programs invoked by an ebuild that may read or modify the home directory. For example: "${PORTAGE_BUILDDIR}/homedir".
ROOT The absolute path to the root directory into which the package is to be merged. Only allowed in pkg_* phases. See ROOT
DISTDIR Contains the path to the directory where all the files fetched for the package are stored.
EPREFIX The normalised offset-prefix path of an offset installation. See Gentoo Prefix Technical Documentation for more information.
ED Shorthand for ${D%/}${EPREFIX}/.
EROOT Shorthand for ${ROOT%/}${EPREFIX}/.
SYSROOT (EAPI=7) The absolute path to the root directory containing build dependencies satisfied by DEPEND
ESYSROOT (EAPI=7) Shorthand for ${SYSROOT%/}${EPREFIX}/.
BROOT (EAPI=7) The absolute path to the root directory containing build dependencies satisfied by BDEPEND, typically executable build tools.
MERGE_TYPE The type of package that is being merged. Possible values are: source if building and installing a package from source, binary if installing a binary package previously built from the ebuild, buildonly if building a binary package without installing it.
REPLACING_VERSIONS A whitespace-separated list of all versions (PVR) of this package that are being replaced (uninstalled or overwritten) as a result of this install. It is a list, not a single optional value, to handle pathological cases such as installing foo-2:2 to replace foo-2:1 and foo-3:2. Available in pkg_preinst and pkg_postinst.
REPLACED_BY_VERSION The single version (PVR) of this package that is replacing the version provided by this ebuild, if it is being uninstalled as part of an install. An empty string otherwise, i.e., if it is being uninstalled without replacement. Available in pkg_prerm and pkg_postrm.

Ebuild-defined Variables

The following variables may or must be defined by every ebuild.

Variable Purpose
EAPI The EAPI. See EAPI Usage and Description.
DESCRIPTION A short (not more than 80 characters) description of the package's purpose. Mandatory.
HOMEPAGE Package's homepage(s). Mandatory (except for virtuals), accepts multiple values. In some contexts, it is customary to provide package tracker and/or code hosting links besides the main homepage (e.g. PyPI link for Python packages, GitHub link when code can't easily be found on homepage) for convenience. If no homepage for the package is available, please set it to https://wiki.gentoo.org/wiki/No_homepage. Never refer to a variable name in the string; include only raw text.
SRC_URI A list of source URIs for the package. Can contain USE-conditional parts, see SRC_URI.
LICENSE The package's license, corresponding exactly (including case) to a file in licenses/. Mandatory (except for virtuals). See LICENSE.
SLOT The package's SLOT. Mandatory. See SLOT.
KEYWORDS See KEYWORDS and Keywording and Stabilization.
IUSE A list of all USE flags (excluding arch flags, but including USE_EXPAND flags) used within the ebuild. See IUSE.
REQUIRED_USE A list of assertions that must be met by the configuration of USE flags to be valid for this ebuild. See REQUIRED_USE.
PROPERTIES A space-delimited list of properties, with conditional syntax support. interactive is the only valid value for now.
RESTRICT A space-delimited list of portage features to restrict. Valid values are fetch, mirror, strip, test and userpriv. See man 5 ebuild for details.
DEPEND A list of the package's build dependencies. See Dependencies. Starting with EAPI-7, applies to CHOST only.
BDEPEND (EAPI=7) A list of the package's CBUILD build dependencies. See Dependencies.
RDEPEND A list of the package's runtime dependencies. See Dependencies.
PDEPEND A list of packages to be installed (if possible) after the package is merged. Use this only when RDEPEND would cause cyclic dependencies. See Dependencies.
S Path to the temporary build directory, used by src_compile and src_install. Default: "${WORKDIR}/${P}". Ebuilds should not provide a value for this variable if it is the same as the default value.
DOCS An array or whitespace-separated list of documentation files for the default src_install function to install using dodoc. If undefined, a reasonable default list is used. See the default src_install function.
HTML_DOCS An array or space-delimited list of documentation files or directories for the einstalldocs function to install recursively. (Requires EAPI>=6.)

SLOT

When slots are not needed, use SLOT="0". Do not use SLOT="", because the variable must not be empty.

See Slotting for more information on this variable.

KEYWORDS

The only valid construct involving a * inside KEYWORDS is a -*. Do not use KEYWORDS="*" or KEYWORDS="~*".

See Keywording and Stabilization for how to handle this variable.

SRC_URI

Conditional Sources

Conditional source files based upon USE flags are allowed using the usual flag? ( ) syntax. This is often useful for arch-specific code or for binary packages — downloading sparc binaries on ppc would be a waste of bandwidth.

SRC_URI="https://example.com/files/${P}-core.tar.bz2
	x86?   ( https://example.com/files/${P}/${P}-sse-asm.tar.bz2 )
	ppc?   ( https://example.com/files/${P}/${P}-vmx-asm.tar.bz2 )
	sparc? ( https://example.com/files/${P}/${P}-vis-asm.tar.bz2 )
	doc?   ( https://example.com/files/${P}/${P}-docs.tar.bz2 )"

Renaming Sources

Sometimes the upstream URI uses generic names that can easily clash with other packages when creating a single mirror. Using the -> syntax allows you to rename the file when it's fetched from upstream for storing on mirrors and in the local distdir.

Here we download a file from upstream which has a plain name like 1.0.tar.gz and save/mirror it with a better name like thepackage-1.0.tar.gz. As usual, all tokens, including the operator and the output file name, must be separated by whitespace.

SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz"

Third-party mirrors

If the items in SRC_URI are available on multiple third-party mirrors, and the same set of mirrors is shared across multiple ebuilds, then you don't have to repeatedly list each of them in every ebuild. The profiles/thirdpartymirrors file in the ::gentoo repository contains named groups of mirrors, in the format specified by the Package Manager Specification (PMS), accessible through the mirror:// pseudo-protocol.

One might define a set of "example" mirrors,

example https://download.example.com https://mirror1.example.org/example

that can afterwards be referenced through a mirror:// URI:

SRC_URI="mirror://example/${PN}/${P}.tar.gz"

There are two valid cases for using thirdpartymirrors:

  1. providing multiple download locations for mirror- or fetch-restricted packages,
  2. dealing with upstreams that distribute their distfiles via a network of mirrors without a primary download location or a bouncer service.

In any other case, the primary location must be used instead. The distfiles will be mirrored onto Gentoo infrastructure; in that case, the benefit to using third-party mirror list does not outweigh the burden of maintaining it.

IUSE

Note that the IUSE variable is cumulative, so there is no need to specify USE flags used only within inherited eclasses within the ebuild's IUSE.

Arch USE flags (sparc, mips, x86-fbsd and so on) should not be listed.

LICENSE

It is possible to specify multiple LICENSE entries, and entries which only apply if a particular USE flag is set. The format is the same as for DEPEND. See GLEP 23 for details.

ROOT

The idea behind ROOT is that one can build a system with ROOT=/somewhere and then chroot into it or tar up /somewhere as a system image. It is not designed to allow the user to run /somewhere/usr/bin/foo.

Ebuilds may reference ROOT only during pkg_* phases. It can't be used correctly in src_* phases, since ROOT may be different when merging a binary package. For example, a binary package may be built with ROOT=/ and then installed onto a system using ROOT=/somewhere.

When building a package, ROOT should not be used to satisfy the required dependencies on libraries, headers files etc. Instead, the files on the build system should be specified using /.

In a cross compiling environment, ebuilds must not call any of the binaries inside ROOT since they may not be executable on the build system.

Below is an example of an ebuild that uses ROOT in pkg_postinst() to conditionally print an error message if an old and obsolete configuration file still exists:

pkg_postinst() {
	if [[ -e "${ROOT}/etc/oldconfig" ]]; then
		ewarn "You still have the obsolete config file "
		ewarn "    ${ROOT}/etc/oldconfig."
		ewarn "Please migrate your settings to ${ROOT}/etc/newconfig"
		ewarn "and remove ${ROOT}/etc/oldconfig."
	fi
}

Version and Name Formatting Issues

Often upstream's tarball versioning or naming format doesn't quite follow Gentoo conventions. Using capital letters in names or differences in how underscores and hyphens are used in versions are particularly common. For example, what Gentoo calls foo-1.2.3b may be expecting a tarball named Foo-1.2-3b.tar.bz2. Rather than hard coding the package string, it is preferable to make MY_PN, MY_PV and MY_P variables and use those to define the upstream naming. EAPI=7 debuted a new set of functions, ver_cut, ver_rs and ver_test. These were backported into older EAPIs with the eapi7-ver eclass. The easy way of redefining the version, which should be used unless you are sure you know what you are doing, is to use these functions:

inherit eapi7-ver
MY_PN="Foo"
# Replace the second period separator in PV with -
MY_PV=$(ver_rs 2 '-')
MY_P="${MY_PN}-${MY_PV}"

This code has the advantage that it will carry on working even if upstream switches to a format like Foo-1.3-4.5.tar.bz2 (yes, this really happens).

It is also possible to use bash substitution to achieve the same effect (this is how eapi7-ver works internally), but this is complicated, error prone and hard to read.

Some ebuilds use calls to sed, awk and / or cut to do this. This must not be done for any new code, and should be fixed to use either eapi7-ver or bash substitution where possible. Global scope non-bash code is highly discouraged.

The ver_ functions are used extract particular components from a version string. See man eapi7-ver.eclass and the eclass source code for further documentation and examples. A brief summary of the functions follows.

Function Purpose
ver_rs [range] ' ' Get important version components, excluding '.', '-' and '_'.
ver_cut 1 Get the major version.
ver_cut [range] Extract a range of subparts from a version string.
ver_cut 2- Get everything after the major version.
ver_rs [range] [char] Replace a particular version separator.
ver_rs 1- [char] Replace all version separators.
ver_rs [range] '' Delete a version separator.
ver_rs 1- '' Delete all version separators.

Trailing Slashes in Variables

The following variables never end with a trailing slash in EAPI 7: D, ED, ROOT, EROOT. Conversely, in EAPIs preceeding EAPI 7, these variables are guaranteed to end with a trailing slash. When working with EAPIs prior to EAPI 7, developers are encouraged to use the bash suffix removal for the trailing slash and add an explicit / when joining paths. For example: ${D%/}/, ${ED%/}/, ${ROOT%/}/, ${EROOT%/}/.

Use of constant-value variables in ebuilds

Variables have significant value in ebuilds, making it possible to avoid unnecessary repetitions and make maintenance easier. However, references to constant-value variables should be used with care as their excessive use can harm readability and increase maintenance burden (e.g. when renaming a package). In particular, using variables whose values have no direct correlation with the expected string should be avoided.

The examples of beneficial constant-value variable references are:

  • using ${PV} and the variables derived from it (${P}, ${MY_P}…) in SRC_URI and S to avoid having to update those variables for every version bump (assuming that ${PV} is used to indicate the upstream version);
  • using ${PF} in --docdir path — this is a canonical Gentoo path that is always required to match ${PF}.

The examples of bad constant-value variable references are:

  • using ${PN} in HOMEPAGE, EGIT_REPO_URI or the domain of SRC_URI — it breaks URL parsing in editors and terminals, and makes it hard to copy the link for external use (e.g. while reviewing via gitweb),
  • using ${HOMEPAGE} in SRC_URI — it breaks when homepage changes or additional entry is added,
  • using ${PN} (or other unnecessary helper variables) excessively in src_install() — it impairs readability for little benefit and causes a lot of trouble when the package needs to be renamed.

REQUIRED_USE

The REQUIRED_USE variable contains a list of assertions that must be met by the configuration of USE flags to be valid for this ebuild. In order to be matched, a USE flag in a terminal element must be enabled (or disabled if it has an exclamation mark prefix).

Essentially, REQUIRED_USE is an analogue of DEPEND style syntax. For example, to state that some combination is forbidden, i.e. "if foo is set, bar must be unset":

REQUIRED_USE="foo? ( !bar )"

To state "if foo is set, then at least one of bar, baz, and quux must be activated":

REQUIRED_USE="foo? ( || ( bar baz quux ) )"

To state "exactly one of foo, bar, or baz must be set, but not several":

REQUIRED_USE="^^ ( foo bar baz )"

Note that the last relationship is that of an Exclusive OR (XOR). While an XOR could be formed from usual DEPEND syntax, a specific ^^ operator has been added for this case.

Finally, to state "at least one of foo, bar, or baz must be set":

REQUIRED_USE="|| ( foo bar baz )"

EAPI 5

EAPI 5 added an additional case to simplify conflicting USE flags.

To state "zero or one of foo, bar, or baz must be set, but not several":

REQUIRED_USE="?? ( foo bar baz )"

In the previous EAPI, this would be the same as:

REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )"