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 package's files/ directory, commonly used for small
patches and other 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 .
|
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
}
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 , live , and test_network are valid values.
|
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.)
|
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, 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
:
- providing multiple download locations for mirror- or fetch-restricted packages,
- 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.
Lifting restrictions
In EAPI 8, individual items in SRC_URI
can be exempted from automatic
mirroring and fetching restrictions (imposed by RESTRICT="mirror"
and
RESTRICT="fetch"
) by prefixing the addresses with mirror+
or
fetch+
. For example, in the following ebuild,
EAPI="8"
SRC_URI="${P}.tar.gz
mirror+https://dev.gentoo.org/~larry/distfiles/${P}-addons.tar.gz"
RESTRICT="fetch"
Portage will be prevented from trying to fetch ${P}.tar.gz
as expected,
but the ${P}-patches.tar.gz
file will be mirrored and fetched by Portage
without restriction.
The following table shows the effects of the prefixes when RESTRICT="mirror"
and RESTRICT="fetch"
are set:
(no prefix) | fetch+ |
mirror+ |
|
---|---|---|---|
(no RESTRICT) | fetch & mirror | fetch & mirror | fetch & mirror |
RESTRICT="mirror" |
fetch only | fetch only | fetch & mirror |
RESTRICT="fetch" |
unfetchable | fetch only | fetch & mirror |
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.
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 and see Package and slot moves.
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.
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
, x64-macos
and so on) should
not be listed.
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 )"
REQUIRED_USE
.
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 )"
RESTRICT
While Portage may recognise several different RESTRICT
tokens, it is
important that you do not rely on them existing. That is, you should ensure
your ebuild does not fail if those tokens are not exposed or given a different
name by another package manager. You can make use of Portage-provided
RESTRICT
tokens, but do not fail hard without them. See the
Package Manager Specification for the list of standardised
RESTRICT
tokens, or the above table.
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 theEBUILD_PHASE
andEBUILD_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.
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. |
versionator.eclass
functions can be found
here, courtesy of Gentoo developer mgorny.
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}
…) inSRC_URI
andS
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}
inHOMEPAGE
,EGIT_REPO_URI
or the domain ofSRC_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}
inSRC_URI
— it breaks when homepage changes or additional entry is added, -
using
${PN}
(or other unnecessary helper variables) excessively insrc_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}
.
Variable | Purpose | Origin | Example |
---|---|---|---|
AR |
ar-compatible library archiver | POSIX make | x86_64-pc-linux-gnu-ar |
ARFLAGS |
flags for ${AR}
|
POSIX make | -v |
AS |
as-compatible assembler | GNU make | x86_64-pc-linux-gnu-as |
ASFLAGS |
flags for ${AS}
|
GNU make | --reduce-memory-overheads |
CC |
C compiler driver (also usually used for linking) | POSIX make | clang-9 |
CFLAGS |
flags for ${CC}
|
POSIX make | -march=native |
CPPFLAGS |
flags for the C preprocessor | GNU make | -D_GNU_SOURCE |
CXX |
C++ compiler driver (also usually used for linking) | GNU make | clang++ |
CXXFLAGS |
flags for ${CXX}
|
GNU make | -fvisibility=hidden |
LD |
dynamic linker | GNU libtool | x86_64-pc-linux-gnu-ld |
LDFLAGS |
flags for the compiler driver to pass to its linker | POSIX make | -Wl,-O1 -Wl,--as-needed |
LEX |
lex-compatible lexer | POSIX make | /usr/bin/flex |
LFLAGS |
flags for ${LEX}
|
POSIX make | --8bit --posix-compat |
NM |
nm-compatible symbol extractor | GNU libtool | x86_64-pc-linux-gnu-nm |
RANLIB |
archive index generator | GNU libtool | x86_64-pc-linux-gnu-ranlib |
YACC |
yacc-compatible compiler-compiler | POSIX make | /usr/bin/bison |
YFLAGS |
flags for ${YACC}
|
POSIX make | -d |