Ebuild environment

Ebuilds are sourced and executed by bash, in an environment that the package manager controls. This section describes the properties of that environment which ebuilds may rely on.

Bash version

Ebuilds and eclasses may use the features of the bash version that their EAPI guarantees:

EAPI	Bash version
7	4.2
8	5.0
9	5.3

Important: Do not use features of a newer bash version than the EAPI allows, even if the bash installed on your system supports them. Doing so will break on systems with an older bash. Note also that the package manager sets bash's compatibility level to the version listed above, so behaviour that has changed between bash versions will follow the older version.

Locale settings

For characters in the ASCII range, case modification and collation order (LC_CTYPE and LC_COLLATE) are guaranteed to behave as in the C locale. Ebuilds can therefore rely on bash constructs like ${var^^} or on the sorting order of glob expansion, without having to set these variables themselves.

Note: This guarantee covers the ebuild environment only. External commands that generate output which the ebuild parses may still be affected by the user's locale.

Filtering the environment

The ENV_UNSET variable holds a whitespace delimited list of variables that the package manager removes from the environment before sourcing an ebuild. It is set in profiles and in make.conf, not in ebuilds.

Its purpose is to keep variables from the calling user's environment from leaking into builds and changing their outcome. The profiles use it for variables such as the XDG_* directory settings, which are meaningless for a build and regularly break one when they are inherited from a running desktop session.

Note: Ebuilds must not rely on ENV_UNSET to protect them. If a build is sensitive to some variable, unset or override it in the ebuild itself.

Failed glob expansion

The failglob option of bash is set in the global scope of ebuilds. As a consequence, a pattern that matches no file results in an error when the ebuild is being sourced, instead of being silently left as a literal string.

This mostly affects arrays that are populated from ${FILESDIR} in global scope:

PATCHES=( "${FILESDIR}"/${P}-*.patch )

If no patch matches the pattern, sourcing the ebuild fails, which will break even simple operations like dependency resolution. Reference the files explicitly to avoid this:

PATCHES=(
	"${FILESDIR}"/${P}-fix-build.patch
	"${FILESDIR}"/${P}-musl.patch
)

Note: failglob is only set while the ebuild is being sourced, i.e. in global scope. It does not apply inside phase functions.