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
app-doc/pms
in the main tree.
You must set the EAPI variable by specifying it at the top of the ebuild:
# Copyright 1999-2020 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 3
EAPIs 0 to 3 are obsolete and must no longer be used. Refer to the Package Manager Specification for details about them.
EAPI=4
EAPI 4 Helpers
-
utilities die on their own, unless the nonfatal command is used
Ebuild functions all die on their own in EAPI=4. In case that this non-zero exit status is expected, you may call
nonfatal function [arg,...]
.Example:
EAPI=2 ... src_test() { if ! emake check ; then local a eerror "Tests failed. Looking for files for you to add to your bug report..." while IFS='' read -r -d $'\0' a ; do eerror " ${a}" done < <(find "${S}" -type f '(' -name '*.epicfail' -o -name '*.log' ')' -print0) die "Make check failed" fi }
EAPI=4 ... src_test() { if ! nonfatal emake check ; then local a eerror "Tests failed. Looking for files for you to add to your bug report..." while IFS='' read -r -d $'\0' a ; do eerror " ${a}" done < <(find "${S}" -type f '(' -name '*.epicfail' -o -name '*.log' ')' -print0) die "Make check failed" fi }
-
recursive dodoc
dodoc
supports-r
as the first argument, which leadsdodoc
to install the specified documentation directory recursively into the docdir.Example:
src_install() { default dodoc ChangeLog dodoc -r doc/ }
-
doins symlink supports
Within EAPI=4,
doins
supports installing symlinks as symlinks when installing recursively. For older EAPIs, the symlink behaviour is undefined. -
dosed and dohard are banned
The
dosed
anddohard
commands are banned in this EAPI. -
econf adds --disable-dependency-tracking
Within EAPI=4,
econf
adds--disable-dependency-tracking
to the default configure options. -
controllable compression via docompress
To compress files in the destination-folder
${D}
, thedocompress
command may be used insrc_install
. To control which items should be compressed and which shouldn't be compressed, you may include or exclude directories or plain files. The default inclusion list contains:/usr/share/doc
/usr/share/info
/usr/share/man
The default exclusion list contains:
/usr/share/doc/${PF}/html
When a directory is in- or excluded, all files and directories in the given directories shall be added to the corresponding list. If a file is in- or excluded, the file shall be added to the corresponding list (exclusion is stronger than inclusion — if a file is in both lists, the inclusion will be ignored).
If the first argument of
docompress
is-x
, the items specified will be added to the exclusion list, otherwise they will be added to the inclusion list.Note: Whendocompress
is called, it is not required that the paths specified as its arguments are pointing to existing files or directories. However, if a file still doesn't exist whensrc_install
has completed, it will be ignored with a warning.
EAPI 4 Metadata
-
use dependencies default
In addition to the use-deps specified in EAPI=2, a
(+)
or(-)
may be added to the use-dep to define a default-value in case the use-flag does not exist in the given package. The(+)
means that this use-flag is assumed to be enabled,(-)
the opposite.Example:
DEPEND=" >=dev-libs/boost-1.32[boost(+)] sys-devel/gcc[openmp(-)]"
EAPI 4 Phases
-
new pkg_pretend phase
The new
pkg_pretend
phase can be used to do sanity checks before the main phase function sequence is run (meaning this phase is executed after the package manager has calculated the dependencies and before installing them). This phase typically checks for a kernel configuration and mayeerror
anddie
when needed.Important: There is no guarantee that the ebuild's dependencies are installed when this phase is called.Important: Aspkg_pretend
is not called in the main phase function sequence, environment saving is not guaranteed.Example:
# Copyright 1999-2020 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 EAPI=4 inherit linux-info ... CONFIG_CHECK="FUSE_FS" ERROR_FUSE_FS="this is an unrealistic testcase..." pkg_pretend() { if use kernel_linux ; then if [[ -e "${ROOT}"/usr/src/linux/.config ]] ; then if kernel_is lt 2 6 30 ; then check_extra_config fi fi fi }
-
default src_install is no longer a no-op
The default
src_install
function in EAPI=4:src_install() { if [[ -f Makefile ]] || [[ -f GNUmakefile]] || [[ -f makefile ]] ; then emake DESTDIR="${D}" install fi if ! declare -p DOCS >/dev/null 2>&1 ; then local d for d in README* ChangeLog AUTHORS NEWS TODO CHANGES THANKS BUGS \ FAQ CREDITS CHANGELOG ; do [[ -s "${d}" ]] && dodoc "${d}" done elif declare -p DOCS | grep -q "^declare -a " ; then dodoc "${DOCS[@]}" else dodoc ${DOCS} fi }
-
pkg_info for non-installed packages
The
pkg_info
function may also be called by the package manager for non-installed packages. Ebuild writers should note that dependencies may not be available.
EAPI 4 Variables
-
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).See REQUIRED_USE
-
REPLACING_VERSIONS and REPLACED_BY_VERSION
The
REPLACING_VERSIONS
variable contains 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 installingfoo-2:2
to replacefoo-2:1
andfoo-3:2
.REPLACING_VERSIONS
is valid inpkg_preinst
andpkg_postinst
. In addition, it may be available inpkg_pretend
andpkg_setup
, although you should take care to handle binary package creation and installation correctly when using it in these phases.The
REPLACED_BY_VERSION
variable contains the single version (PVR
) of this package that is replacing us, if we are being uninstalled as part of an install, or an empty string otherwise. It is valid inpkg_prerm
andpkg_postrm
. -
MERGE_TYPE
The
MERGE_TYPE
variable contains 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,
buildonly
- if building a binary package without installing it.
-
DOCS
The
DOCS
variable is an array or whitespace-separated list of documentation files for the defaultsrc_install
function to install usingdodoc
. If undefined, a reasonable default list is used. See the defaultsrc_install
function above. -
AA and KV variables are gone
The
AA
andKV
variables are no longer set in EAPI=4. -
no more RDEPEND="${DEPEND}"
When
RDEPEND
is unset, there will no longer be an automatic assignment ofRDEPEND="${DEPEND}"
.
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.Note: use:slot/subslot
without a=
to depend on a specific slot and sub-slot pair; it's a syntax error to use:slot/subslot=
in an ebuild.
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 ofbaz
orwombat: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
andpackage.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 ofconfigure --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
orsrc_unpack
), theEBUILD_PHASE_FUNC
variable will contain the name of the phase function that is currently executing.
EAPI=6
EAPI 6 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
andLC_COLLATE
) are guaranteed to be the same as in the C locale, as far as characters in the ASCII range are concerned. -
failglob
enabledFor
EAPI=6
, thefailglob
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 viaeapply_user
. The defaultsrc_prepare
looks like this:src_prepare() { if declare -p PATCHES | grep -q "^declare -a "; then [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}" else [[ -n ${PATCHES} ]] && eapply ${PATCHES} fi eapply_user }
-
New
src_install
Phase FunctionThis phase uses the new
einstalldocs
function for installation of documentation. The defaultsrc_install
looks like this:src_install() { if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then emake DESTDIR="${D}" install fi einstalldocs }
EAPI 6 Helpers
-
einstall
bannedThe
einstall
helper has been banned withEAPI=6
. -
dohtml
deprecatedThe
dohtml
helper has been deprecated withEAPI=6
. -
nonfatal die
When
die
orassert
are called under thenonfatal
command and with the-n
option, they will not abort the build process but return with an error. -
eapply
supportThe
eapply
command is a simplified substitute forepatch
(fromeutils.eclass
), implemented in the package manager. The patches from its file or directory arguments are applied using patch-p1
, but it acceptspatch(1)
options from GNU patch to override default behavior. -
eapply_user
supportThe
eapply_user
command permits the package manager to apply user-provided patches. It must be called from everysrc_prepare
function.Note:eapply_user
doesn't need to be called explicitly when defaultsrc_prepare
is called. -
econf
adds--docdir
and--htmldir
Options
--docdir
and--htmldir
are passed toconfigure
, in addition to the existing options. -
in_iuse
supportThe
in_iuse
function returnstrue
if the given parameter is available in the ebuildsUSE
. -
unpack
changesunpack
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
supportThe
einstalldocs
function will install the files specified by theDOCS
variable (or a default set of files ifDOCS
is unset) and by theHTML_DOCS
variable. -
get_libdir
supportThe
get_libdir
command outputs thelib*
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-compliations, often empty value.
EAPI 7 Variables
-
PORTDIR
andECLASSDIR
are removedPORTDIR
andECLASSDIR
are no longer defined and cannot be used in ebuilds to access these directories. -
DESTTREE
andINSDESTTREE
are removedThe unintended exported variables
PORTDIR
andECLASSDIR
cannot be used in ebuilds to manipulate installation paths. Useinto
orinsinto
, respectively, instead. -
D
,ED
,ROOT
, andEROOT
modifiedThese variables no longer contain a trailing slash with
EAPI=7
. -
BDEPEND
adddedPreviously, all build-time tools and libraries went into the
DEPEND
. Now, built-time dependencies are split intoDEPEND
andBDEPEND
. The difference is simply thatBDEPEND
are dependencies to be executed on the CBUILD.DEPEND
remains for other dependencies, such as libraries, for the CHOST. This improves the cross-compliation support. -
BROOT
addedBROOT
is the absolute path to the root directory, including any prefix, containing build dependencies satisfied by BDEPEND, typically executable build tools. -
SYSROOT
andESYSROOT
addedSYSROOT
is the location of where dependencies inDEPEND
are installed.ESYSROOT
isSYSROOT
withEPREFIX
appended. -
ENV_UNSET
addedA 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. Eg.REQUIRED_USE="|| ( foo? ( bar ) baz? ( zoinks )"
would previously work withUSE="-foo -baz"
now requires eitherUSE="foo bar"
orUSE="baz zoinks"
.
EAPI 7 Profiles
-
package.provided
bannedProfiles may no longer contain a
package.provided
file withEAPI=7
.
EAPI 7 Helpers
-
dohtml
bannedThe
dohtml
helper has been banned withEAPI=7
. -
dolib
andlibopts
bannedThe
dolib
helper and the associatedlibopts
have been banned withEAPI=7
. -
has_version
andbest_version
changeshas_version
andbest_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 comparision commands
EAPI=7 introduced three commands for common version number operations.
ver_cut
obtains substrings of a version stringver_rs
replaces separators in a version stringver_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 withEAPI=7
. This function is to alert developers to a deprecated feature. Previously, this was contained ineutils
eclass which is no longer necessary. -
New function
dostrip
The
dostrip
helper has been added withEAPI=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
andassert
changesThese commands are now safe to use in a subshell and act as if they were called in the main process.
-
nonfatal
changesThe
nonfatal
command now works for shell functions and subprocesses. -
domo
behaviour changeddomo
(for localizations) now ignores theinto
directives. This follows similar commands likedoinfo
anddoman
. -
econf
changesThe cross-compilation options
--build
and--target
options to specifyCBUILD
andCTARGET
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-compliations succeed.