EAPI Usage and Description

The Package Manager Specification (PMS) is a standardization effort to ensure that the ebuild file format, the ebuild repository format (of which the Gentoo repository is Gentoo's main incarnation) as well as behaviour of the package managers interacting with these ebuilds is properly written down and agreed upon.

EAPI is a version defined in ebuilds and other package manager related files which informs the package manager about the file syntax and content. It is, in effect, the version of the package manager specification (PMS) that the file adheres to.

This section provides usage and descriptions of the different EAPIs.

Usage of EAPIs

You must set the EAPI variable by specifying it at the top of the ebuild:

# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

EAPI=7

When writing new ebuilds developers can choose whatever EAPI they think is the best. Using the features of the latest EAPI is encouraged.

EAPIs 0 to 4

EAPIs 0 to 4 are obsolete and must no longer be used. Refer to the Package Manager Specification for details about them.

EAPI 5

EAPI 5 Metadata

REQUIRED_USE supports new at-most-one-of operator
The new at-most-one-of operator consists of the string ??, and is satisfied if zero or one (but no more) of its child elements is matched.
SLOT supports optional "sub-slot" part
The SLOT variable may contain an optional sub-slot part that follows the regular slot and is delimited by a / character. The sub-slot must be a valid slot name. The sub-slot is used to represent cases in which an upgrade to a new version of a package with a different sub-slot may require dependent packages to be rebuilt. When the sub-slot part is omitted from the SLOT definition, the package is considered to have an implicit sub-slot which is equal to the regular slot.
Slot operators and sub-slots in dependencies

A slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a / character. This can be useful for packages installing pre-built binaries that require a library with a specific soname version which corresponds to the sub-slot. For example:

RDEPEND="dev-libs/foo:0/3"

Package dependency specifications can use slot operators to clarify what should happen if the slot and/or sub-slot of a runtime dependency changes:

  • :* Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package specifying the dependency will not break if the package matching the dependency is replaced by a different matching package with a different slot and/or sub-slot.
  • := Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package specifying the dependency will break unless there is available a package matching the dependency and whose slot and sub-slot are equal to the slot and sub-slot of the best installed version that had matched this dependency at the time when the package specifying this dependency had been installed.
  • :slot= Indicates that only a specific slot value is acceptable, and otherwise behaves identically to the := operator.

The :slot dependency syntax continues to behave like in EAPI=4 or earlier, i.e. it indicates that only the specific slot value is acceptable, but the package will not break when the version matching the runtime dependency is replaced by a version with a different sub-slot.

For example:

RDEPEND="dev-libs/foo:2=
    >=dev-libs/bar-0.9:=
    media-gfx/baz:*
    x11-misc/wombat:0"

means that the package should be rebuilt when foo:2 or >=bar-0.9 are upgraded to versions with different subslots, but that changes in subslots of baz or wombat:0 should be ignored.

EAPI 5 Profiles

Profile stable USE forcing and masking
In profile directories with an EAPI supporting stable masking, new USE configuration files are supported: use.stable.mask, use.stable.force, package.use.stable.mask and package.use.stable.force. These files behave similarly to previously supported USE configuration files, except that they only influence packages that are merged due to a stable keyword.

EAPI 5 Helpers

econf adds --disable-silent-rules
This option will automatically be passed if --disable-silent-rules occurs in the output of configure --help.
new* commands can read from standard input
Standard input is read when the first parameter is - (a hyphen).
New option --host-root for {has,best}_version
This option --host-root will cause the query to apply to the host root instead of ROOT.
New doheader helper function
Installs the given header files into /usr/include/. If option -r is specified, descends recursively into any directories given.
New usex helper function
USAGE: usex <USE flag> [true output] [false output] [true suffix] [false suffix]
DESCRIPTION:
If USE flag is set, echo [true output][true suffix] (defaults to "yes"),
 otherwise echo [false output][false suffix] (defaults to "no").

EAPI 5 Phases

src_test supports parallel tests
Unlike older EAPIs, the default src_test implementation will not pass the -j1 option to emake.

EAPI 5 Variables

EBUILD_PHASE_FUNC
During execution of an ebuild phase function (such as pkg_setup or src_unpack), the EBUILD_PHASE_FUNC variable will contain the name of the phase function that is currently executing.

EAPI 6

EAPI 6 Bash version

Bash version
Ebuilds can use features of Bash version 4.2 (was 3.2 before).

EAPI 6 Ebuild Environment

Locale settings
Behaviour of case modification and collation order (LC_CTYPE and LC_COLLATE) are guaranteed to be the same as in the C locale, as far as characters in the ASCII range are concerned.
failglob enabled
For EAPI=6, the failglob option of bash is set in the global scope of ebuilds. If set, failed pattern matches during filename expansion result in an error when the ebuild is being sourced.

EAPI 6 Phases

Update default implementation of src_prepare

This phase is no longer a no-op, it supports applying patches via the PATCHES variable and applying user patches via eapply_user. The default src_prepare looks like this:

src_prepare() {
    if [[ $(declare -p PATCHES 2>/dev/null) == "declare -a"* ]]; then
        [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}"
    else
        [[ -n ${PATCHES} ]] && eapply ${PATCHES}
    fi
    eapply_user
}
New src_install Phase Function

This phase uses the new einstalldocs function for installation of documentation. The default src_install looks like this:

src_install() {
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake DESTDIR="${D}" install
    fi
    einstalldocs
}

EAPI 6 Helpers

einstall banned
The einstall helper has been banned with EAPI=6.
dohtml deprecated
The dohtml helper has been deprecated with EAPI=6.
nonfatal die
When die or assert are called under the nonfatal command and with the -n option, they will not abort the build process but return with an error.
eapply support
The eapply command is a simplified substitute for epatch (from eutils.eclass), implemented in the package manager. The patches from its file or directory arguments are applied using patch -p1, but it accepts patch(1) options from GNU patch to override default behavior.
eapply_user support

The eapply_user command permits the package manager to apply user-provided patches. It must be called from every src_prepare function.

econf adds --docdir and --htmldir
Options --docdir and --htmldir are passed to configure, in addition to the existing options.
in_iuse support
The in_iuse function returns true if the given parameter is available in the ebuilds USE.
unpack changes
  • unpack supports relative paths without leading ./ (unpack foo/bar.tar.gz is valid as relative path).
  • unpack supports .txz (xz compressed tarball).
  • unpack matches filename extensions case-insensitively.
einstalldocs support
The einstalldocs function will install the files specified by the DOCS variable (or a default set of files if DOCS is unset) and by the HTML_DOCS variable.
get_libdir support
The get_libdir command outputs the lib* directory basename suitable for the current ABI.

EAPI 7

EAPI 7 Terminology

Documents may use the following terms to better describe dependency and installation targets.

CHOST
The system that will be running the installed package.
CBUILD
The system used to build packages. When not cross-compiling, CBUILD == CHOST.
CTARGET
Used in certain cross-compilations, often empty value.

EAPI 7 Variables

PORTDIR and ECLASSDIR are removed
PORTDIR and ECLASSDIR are no longer defined and cannot be used in ebuilds to access these directories.
DESTTREE and INSDESTTREE are removed
The unintended exported variables PORTDIR and ECLASSDIR cannot be used in ebuilds to manipulate installation paths. Use into or insinto, respectively, instead.
D, ED, ROOT, and EROOT modified
These variables no longer contain a trailing slash with EAPI=7.
BDEPEND added
Previously, all build-time tools and libraries went into the DEPEND. Now, built-time dependencies are split into DEPEND and BDEPEND. The difference is simply that BDEPEND are dependencies to be executed on the CBUILD. DEPEND remains for other dependencies, such as libraries, for the CHOST. This improves the cross-compilation support.
BROOT added
BROOT is the absolute path to the root directory, including any prefix, containing build dependencies satisfied by BDEPEND, typically executable build tools.
SYSROOT and ESYSROOT added
SYSROOT is the location of where dependencies in DEPEND are installed. ESYSROOT is SYSROOT with EPREFIX appended.
ENV_UNSET added
A whitespace delimited list of variables to be removed from the build environment.

EAPI 7 Metadata

Empty groupings are banned
Groupings which are empty, such as DEPEND="|| ( ${empty_var} )" will now generate an error. Furthermore, conditions within groupings are more strictly enforced. For example, REQUIRED_USE="|| ( foo? ( bar ) baz? ( zoinks )" would previously work with USE="-foo -baz" now requires either USE="foo bar" or USE="baz zoinks".

EAPI 7 Profiles

package.provided banned
Profiles may no longer contain a package.provided file with EAPI=7.

EAPI 7 Helpers

dohtml banned
The dohtml helper has been banned with EAPI=7.
dolib and libopts banned
The dolib helper and the associated libopts have been banned with EAPI=7.
has_version and best_version changes

has_version and best_version now support an optional switch to determine which type of dependencies to check.

  • -r (the default) will check runtime dependencies (RDEPEND)
  • -d will check CHOST build-time dependencies (DEPEND)
  • -b will check CBUILD build-time dependencies (BDEPEND)
Version manipulation and comparison commands

EAPI=7 introduced three commands for common version number operations.

  • ver_cut obtains substrings of a version string
  • ver_rs replaces separators in a version string
  • ver_test compares two versions

See Version and Name Formatting Issues for examples of common uses or an in-depth look

New function eqawarn
The eqawarn helper has been added with EAPI=7. This function is to alert developers to a deprecated feature. Previously, this was contained in eutils eclass which is no longer necessary.
New function dostrip
The dostrip helper has been added with EAPI=7. This function controls whether or not to strip a binary. dostrip -x [file] will exclude a binary from being stripped. Conversely, when combined with RESTRICT=strip, dostrip [file] selects a binary file to be stripped.
die and assert changes
These commands are now safe to use in a subshell and act as if they were called in the main process.
nonfatal changes
The nonfatal command now works for shell functions and subprocesses.
domo behaviour changed
domo (for localizations) now ignores the into directives. This follows similar commands like doinfo and doman.
econf changes
The cross-compilation options --build and --target options to specify CBUILD and CTARGET respectively have been added and are retro-active to all EAPIs. In addition, if the build supports --with-sysroot, the correct value will be passed such that normal and cross-compilations succeed.