Variables

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.

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
}

Ebuild-defined variables

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

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 )"

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

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

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

EAPI="8"

SRC_URI="${P}.tar.gz
	mirror+https://dev.gentoo.org/~larry/distfiles/${P}-addons.tar.gz"

RESTRICT="fetch"

REQUIRED_USE="foo? ( !bar )"

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

REQUIRED_USE="^^ ( foo bar baz )"

REQUIRED_USE="|| ( foo bar baz )"

REQUIRED_USE="?? ( foo bar baz )"

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

Variables reserved for the package manager

Variables and functions that begin with any of the following strings (ignoring case) are reserved for package manager use. Ebuilds must neither use them nor rely upon them:

• __ (two underscores)
• abort
• dyn
• prep

The same applies to functions and variables that contain any of the following strings (ignoring case):

• ebuild (unless immediately preceded by another letter, and except for the EBUILD_PHASE and EBUILD_PHASE_FUNC variables)
• hook
• paludis
• portage

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

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, 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 the built-in version manipulation commands or Bash substitution. Global scope non-Bash code is strongly discouraged.

The ver_ functions are used extract particular components from a version string. See Version functions reference for further documentation and examples. A brief summary of the functions follows.

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.

User environment

The following variables may be set in the user's environment and should be respected by all ebuilds. The purpose of each variable within Gentoo is listed alongside an example of a valid value. Upstream usage may diverge, but ebuilds should ensure that these variables are interpreted consistently within Gentoo. The chosen meanings are inspired by a few real and de-facto standards:

• The POSIX (2018) make specification
• The GNU make (v4.3) implementation
• The GNU libtool (v2.4.6) package

Many of these variables only have an effect if they are invoked directly. For example, your compiler driver is usually responsible for assembling object files rather than a direct call to ${AS}. In that case, setting ASFLAGS will have no effect on the build process; instead, you would set something like CFLAGS="-Wa,-alh,-L" to tell the C compiler to pass those flags to the assembler. The LDFLAGS variable is the exception to this rule, as it is intended to be passed to the compiler driver rather than ${LD}.