Thanks to Mike Kelly (package manager provided utilities, section 11.3.3), Danny van Dyk (ebuild functions, section 9), David Leverton (various sections), Petteri Räty (environment state, section 11.2) and Michał Górny (various sections) for contributions. Thanks also to Mike Frysinger and Brian Harring for proof-reading and suggestions for fixes and/or clarification.
The bulk of this document is © 2007–2017 Stephen Bennett, Christian Faulhammer, Ciaran McCreesh and Ulrich Müller. Contributions are owned by their respective authors, and may have been changed substantially before inclusion.
This document is released under the Creative Commons Attribution-Share Alike 3.0 Licence. The full text of this licence can be found at http://creativecommons.org/licenses/by-sa/3.0/.
Issues (inaccuracies, wording problems, omissions etc.) in this document should be reported via Gentoo Bugzilla using product Gentoo Hosted Projects, component PMS/EAPI and the default assignee. There should be one bug per issue, and one issue per bug.
Patches (in git format-patch form if possible) may be submitted either via Bugzilla or to the gentoo-pms@lists.gentoo.org mailing list. Patches will be reviewed by the PMS team, who will do one of the following:
When reporting issues, remember that this document is not the appropriate place for pushing through changes to the tree or the package manager, except where those changes are bugs.
If any issue cannot be resolved by the PMS team, it may be escalated to the Gentoo Council.
This document aims to fully describe the format of an ebuild repository and the ebuilds therein, as well as certain aspects of package manager behaviour required to support such a repository.
This document is not designed to be an introduction to ebuild development. Prior knowledge of ebuild creation and an understanding of how the package management system works is assumed; certain less familiar terms are explained in the Glossary in chapter 14.
This document does not specify any user or package manager configuration information.
At present the only definition of what an ebuild can assume about its environment, and the only definition of what is valid in an ebuild, is the source code of the latest Portage release and a general consensus about which features are too new to assume availability. This has several drawbacks: not only is it impossible to change any aspect of Portage behaviour without verifying that nothing in the tree relies upon it, but if a new package manager should appear it becomes impossible to fully support such an ill-defined standard.
This document aims to address both of these concerns by defining almost all aspects of what an ebuild repository looks like, and how an ebuild is allowed to behave. Thus, both Portage and other package managers can change aspects of their behaviour not defined here without worry of incompatibilities with any particular repository.
Text in teletype is used for filenames or variable names. Italic text is used for terms with a particular technical meaning in places where there may otherwise be ambiguity.
The term package manager is used throughout this document in a broad sense. Although some parts of this document are only relevant to fully featured package managers, many items are equally applicable to tools or other applications that interact with ebuilds or ebuild repositories.
An EAPI can be thought of as a ‘version’ of this specification to which a package conforms. An EAPI value is a string as per section 3.1.8, and is part of an ebuild’s metadata.
If a package manager encounters a package version with an unrecognised EAPI, it must not attempt to perform any operations upon it. It could, for example, ignore the package version entirely (although this can lead to user confusion), or it could mark the package version as masked. A package manager must not use any metadata generated from a package with an unrecognised EAPI.
The package manager must not attempt to perform any kind of comparison test other than equality upon EAPIs.
EAPIs are also used for profile directories, as described in section 5.2.2.
The following EAPIs are defined by this specification:
Except where explicitly noted, everything in this specification applies to all of the above EAPIs.1
No name may be empty. Package managers must not impose fixed upper boundaries upon the length of any name. A package manager should indicate or reject any name that is invalid according to these rules.
A category name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a hyphen, a dot or a plus sign.
Note: A hyphen is not required because of the virtual category. Usually, however, category names will contain a hyphen.
A package name may contain any of the characters [A-Za-z0-9+_-]. It must not begin with a hyphen or a plus sign, and must not end in a hyphen followed by anything matching the version syntax described in section 3.2.
Note: A package name does not include the category. The term qualified package name is used where a category/package pair is meant.
A slot name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a hyphen, a dot or a plus sign.
A USE flag name may contain any of the characters [A-Za-z0-9+_@-]. It must begin with an alphanumeric character. Underscores should be considered reserved for USE_EXPAND, as described in section 11.1.1.
Note: The at-sign is required for LINGUAS.
A repository name may contain any of the characters [A-Za-z0-9_-]. It must not begin with a hyphen. In addition, every repository name must also be a valid package name.
A license name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a hyphen, a dot or a plus sign.
A keyword name may contain any of the characters [A-Za-z0-9_-]. It must not begin with a hyphen. In contexts where it makes sense to do so, a keyword name may be prefixed by a tilde or a hyphen. In KEYWORDS, -* is also acceptable as a keyword.
An EAPI name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a hyphen, a dot or a plus sign.
The package manager must not impose fixed limits upon the number of version components. Package managers should indicate or reject any version that is invalid according to these rules.
A version starts with the number part, which is in the form [0-9]+(\.[0-9]+)* (a positive integer, followed by zero or more dot-prefixed positive integers).
This may optionally be followed by one of [a-z] (a lowercase letter).
This may be followed by zero or more of the suffixes _alpha, _beta, _pre, _rc or _p, which themselves may be followed by an optional integer. Suffix and integer count as separate version components.
This may optionally be followed by the suffix -r followed immediately by an integer (the “revision number”). If this suffix is not present, it is assumed to be -r0.
Version specifications are compared component by component, moving from left to right, as detailed in Algorithm 3.1 and sub-algorithms. If a sub-algorithm returns a decision, then that is the result of the whole comparison; if it terminates without returning a decision, the process continues from the point from which it was invoked.
No two packages in a given repository may have the same qualified package name and equal versions. For example, a repository may not contain more than one of foo-bar/baz-1.0.2, foo-bar/baz-1.0.2-r0 and foo-bar/baz-1.000.2.
This chapter defines the layout on-disk of an ebuild repository. In all cases below where a file or directory is specified, a symlink to a file or directory is also valid. In this case, the package manager must follow the operating system’s semantics for symbolic links and must not behave differently from normal.
An ebuild repository shall occupy one directory on disk, with the following subdirectories:
Each category provided by the repository (see also: the profiles/categories file, section 4.4) shall be contained in one directory, whose name shall be that of the category. Each category directory shall contain:
Category directories may contain additional files, whose purpose is not covered by this specification. Additional directories that are not for a package may not be present, to avoid conflicts with package name directories; an exception is made for filesystem components whose name starts with a dot, which the package manager must ignore, and for any directory named CVS.
It is not required that a directory exists for each category provided by the repository. A category directory that does not exist shall be considered equivalent to an empty category (and by extension, a package manager may treat an empty category as a category that does not exist).
A package directory contains the following:
Any ebuild in a package directory must be named name-ver.ebuild, where name is the (unqualified) package name, and ver is the package’s version. Package managers must ignore any ebuild file that does not match these rules.
A package directory that contains no correctly named ebuilds shall be considered a package with no versions. A package with no versions shall be considered equivalent to a package that does not exist (and by extension, a package manager may treat a package that does not exist as a package with no versions).
A package directory may contain other files or directories, whose purpose is not covered by this specification.
The profiles directory shall contain zero or more profile directories as described in section 5, as well as the following files and directories. In any line-based file, lines beginning with a # character are treated as comments, whilst blank lines are ignored. All contents of this directory, with the exception of repo_name, are optional.
The profiles directory may contain an eapi file. This file, if it exists, must contain a single line with the name of an EAPI. This specifies the EAPI to use when handling the profiles directory; a package manager must not attempt to use any repository whose profiles directory requires an EAPI it does not support. If no eapi file is present, EAPI 0 shall be used.
If the repository is not intended to be stand-alone, the contents of these files are to be taken from or merged with the master repository as necessary.
Other files not described by this specification may exist, but may not be relied upon. The package manager must ignore any files in this directory that it does not recognise.
profiles.desc is a line-based file, with the standard commenting rules from section 4.4, containing a list of profiles that are valid for use, along with their associated architecture and status. Each line has the format:
Where:
Fields are whitespace-delimited.
thirdpartymirrors is another simple line-based file, describing the valid mirrors for use with mirror:// URIs in this repository, and the associated download locations. The format of each line is:
Fields are whitespace-delimited. When parsing a URI of the form mirror://name/path/filename, where the path/ part is optional, the thirdpartymirrors file is searched for a line whose first field is name. Then the download URIs in the subsequent fields have path/filename appended to them to generate the URIs from which a download is attempted.
Each mirror name may appear at most once in a file. Behaviour when a mirror name appears multiple times is undefined. Behaviour when a mirror is defined in terms of another mirror is undefined. A package manager may choose to fetch from all of or a subset of the listed mirrors, and may use an order other than the one described.
The mirror with the name equal to the repository’s name (and if the repository has a master, the master’s name) may be consulted for all downloads.
use.desc contains descriptions of every valid global USE flag for this repository. It is a line-based file with the standard rules for comments and blank lines. The format of each line is:
use.local.desc contains descriptions of every valid local USE flag—those that apply only to a small number of packages, or that have different meanings for different packages. Its format is:
Flags must be listed once for each package to which they apply, or if a flag is listed in both use.desc and use.local.desc, it must be listed once for each package for which its meaning differs from that described in use.desc.
The updates directory is used to inform the package manager that a package has moved categories, names, or that a version has changed SLOT. It contains one file per quarter year, named [1-4]Q-[YYYY] for the first to fourth quarter of a given year, for example 1Q-2004 or 3Q-2006. The format of each file is again line-based, with each line having one of the following formats:
The first form, where qpn1 and qpn2 are qualified package names, instructs the package manager that the package qpn1 has changed name, category, or both, and is now called qpn2.
The second form instructs the package manager that any currently installed package version matching package dependency specification spec whose SLOT is set to slot1 should have it updated to slot2.
Any name that has appeared as the origin of a move must not be reused in the future. Any slot that has appeared as the origin of a slot move may not be used by packages matching the spec of that slot move in the future.
The licenses directory shall contain copies of the licenses used by packages in the repository. Each file will be named according to the name used in the LICENSE variable as described in section 7.3, and will contain the complete text of the license in human-readable form. Plain text format is strongly preferred but not required.
The eclass directory shall contain copies of the eclasses provided by this repository. The format of these files is described in section 10. It may also contain, in their own directory, support files needed by these eclasses.
The metadata directory contains various repository-level metadata that is not contained in profiles/. All contents are optional. In this standard only the cache subdirectory is described; other contents are optional but may include security advisories, DTD files for the various XML files used in the repository, and repository timestamps.
The metadata/cache directory may contain a cached form of all important ebuild metadata variables. The contents of this directory are described in section 13.
Generally, a profile defines information specific to a certain ‘type’ of system—it lies somewhere between repository-level defaults and user configuration in that the information it contains is not necessarily applicable to all machines, but is sufficiently general that it should not be left to the user to configure it. Some parts of the profile can be overridden by user configuration, some only by another profile.
The format of a profile is relatively simple. Each profile is a directory containing any number of the files described in this chapter, and possibly inheriting another profile. The files themselves follow a few basic conventions as regards inheritance and format; these are described in the next section. It may also contain any number of subdirectories containing other profiles.
A profile may contain a parent file. Each line must contain a relative path to another profile which will be considered as one of this profile’s parents. Any settings from the parent are inherited by this profile, and can be overridden by it. Precise rules for how settings are combined with the parent profile vary between files, and are described below. Parents are handled depth first, left to right, with duplicate parent paths being sourced for every time they are encountered.
It is illegal for a profile’s parent tree to contain cycles. Package manager behaviour upon encountering a cycle is undefined.
This file must not contain comments, blank lines or make use of line continuations.
A profile directory may contain an eapi file. This file, if it exists, must contain a single line with the name of an EAPI. This specifies the EAPI to use when handling the directory in question; a package manager must not attempt to use any profile using a directory which requires an EAPI it does not support. If no eapi file is present, EAPI 0 shall be used. The EAPI is neither inherited via the parent file nor in subdirectories.
If a profile contains a file named deprecated, it is treated as such. The first line of this file should contain the path from the profiles directory of the repository to a valid profile that is the recommended upgrade path from this profile. The remainder of the file can contain any text, which may be displayed to users using this profile by the package manager. This file is not inherited—profiles which inherit from a deprecated profile are not deprecated.
This file must not contain comments or make use of line continuations.
make.defaults is used to define defaults for various environment and configuration variables. This file is unusual in that it is not combined at a file level with the parent—instead, each variable is combined or overridden individually as described in section 5.3.
The file itself is a line-based key-value format. Each line contains a single VAR="value" entry, where the value must be double quoted. A variable name must start with one of a-zA-Z and may contain a-zA-Z0-9_ only. Additional syntax, which is a small subset of bash syntax, is allowed as follows:
These files are a simple one-item-per-line list, which is inherited in the following manner: the parent profile’s list is taken, and the current profile’s list appended. If any line begins with a hyphen, then any lines previous to it whose contents are equal to the remainder of that line are removed from the list. Once again, blank lines and those beginning with a # are discarded.
The packages file is used to define the ‘system set’ for this profile. After the above rules for inheritance and comments are applied, its lines must take one of two forms: a package dependency specification prefixed by * denotes that it forms part of the system set. A package dependency specification on its own may also appear for legacy reasons, but should be ignored when calculating the system set.
The packages.build file is used by Gentoo’s Catalyst tool to generate stage1 tarballs, and has no relevance to the operation of a package manager. It is thus outside the scope of this document, but is mentioned here for completeness.
package.mask is used to prevent packages from being installed on a given profile. Each line contains one package dependency specification; anything matching this specification will not be installed unless unmasked by the user’s configuration.
Note that the -spec syntax can be used to remove a mask in a parent profile, but not necessarily a global mask (from profiles/package.mask, section 4.4).
Note: Portage currently treats profiles/package.mask as being on the leftmost branch of the inherit tree when it comes to -lines. This behaviour may not be relied upon.
package.provided is used to tell the package manager that a certain package version should be considered to be provided by the system regardless of whether it is actually installed. Because it has severe adverse effects on USE-based and slot-based dependencies, its use is strongly deprecated and package manager support must be regarded as purely optional.
The package.use file may be used by the package manager to override the default USE flags specified by make.defaults on a per package basis. The format is to have a package dependency specification, and then a space delimited list of USE flags to enable. A USE flag in the form of -flag indicates that the package should have the USE flag disabled. The package dependency specification is limited to the forms defined by the directory’s EAPI.
This section covers the eight files use.mask, use.force, use.stable.mask, use.stable.force, package.use.mask, package.use.force, package.use.stable.mask, and package.use. stable.force. They are described together because they interact in a non-trivial manner.
Simply speaking, use.mask and use.force are used to say that a given USE flag must never or always, respectively, be enabled when using this profile. package.use.mask and package.use.force do the same thing on a per-package, or per-version, basis.
stablemask In profile directories with an EAPI supporting stable masking, as listed in table 5.1, the same is true for use.stable.mask, use.stable.force, package.use.stable.mask and package.use.stable.force. These files, however, only act on packages that are merged due to a stable keyword in the sense of subsection 7.3.2. Thus, these files can be used to restrict the feature set deemed stable in a package.
EAPI | Supports masking/forcing use flags in stable versions?
|
0, 1, 2, 3, 4 | No |
5, 6 | Yes |
The precise manner in which the eight files interact is less simple, and is best described in terms of the algorithm used to determine whether a flag is masked for a given package version. This is described in Algorithm 5.1.
Stable restrictions (“stable keyword in use” in Algorithm 5.1) are applied exactly if replacing in KEYWORDS all stable keywords by the corresponding tilde prefixed keywords (see subsection 7.3.2) would result in the package installation being prevented due to the KEYWORDS setting.
The logic for use.force, use.stable.force, package.use.force, and package.use. stable.force is identical. If a flag is both masked and forced, the mask is considered to take precedence.
USE_EXPAND values may be forced or masked by using expand_name_value.
A package manager may treat ARCH values that are not the current architecture as being masked.
This section documents variables that have special meaning, or special behaviour, when defined in a profile’s make.defaults file.
Incremental variables must stack between parent and child profiles in the following manner: Beginning with the highest parent profile, tokenise the variable’s value based on whitespace and concatenate the lists. Then, for any token T beginning with a hyphen, remove it and any previous tokens whose value is equal to T with the hyphen removed, or, if T is equal to -*, remove all previous values. Note that because of this treatment, the order of tokens in the final result is arbitrary, not necessarily related to the order of tokens in any given profile. The following variables must be treated in this fashion:
If the package manager supports any EAPI listed in table 5.2 as using profile-defined IUSE injection, the following variables must also be treated incrementally; otherwise, the following variables may or may not be treated incrementally:
Other variables, except where they affect only package-manager-specific functionality (such as Portage’s FEATURES variable), must not be treated incrementally—later definitions shall completely override those in parent profiles.
EAPI | Supports profile-defined IUSE injection?
|
0, 1, 2, 3, 4 | No |
5, 6 | Yes |
The following variables have specific meanings when set in profiles.
In addition, for EAPIs listed in table 5.2 as supporting profile defined IUSE injection, the variables named in USE_EXPAND and USE_EXPAND_UNPREFIXED have special handling as described in section 11.1.1.
Any other variables set in make.defaults must be passed on into the ebuild environment as-is, and are not required to be interpreted by the package manager.
bash-version The ebuild file format is in its basic form a subset of the format of a bash script. The interpreter is assumed to be GNU bash, version as listed in table 6.1, or any later version. If possible, the package manager should set the shell’s compatibility level to the exact version specified. It must ensure that any such compatibility settings (e.g. the BASH_COMPAT variable) are not exported to external programs.
The file encoding must be UTF-8 with Unix-style newlines. When sourced, the ebuild must define certain variables and functions (see sections 7 and 9 for specific information), and must not call any external programs, write anything to standard output or standard error, or modify the state of the system in any way.
Note: This section describes variables that may or must be defined by ebuilds. For variables that are passed from the package manager to the ebuild, see section 11.1.
If any of these variables are set to invalid values, or if any of the mandatory variables are undefined, the package manager’s behaviour is undefined; ideally, an error in one ebuild should not prevent operations upon other ebuilds or packages.
All ebuild-defined variables discussed in this chapter must be defined independently of any system, profile or tree dependent data, and must not vary depending upon the ebuild phase. In particular, ebuild metadata can and will be generated on a different system from that upon which the ebuild will be used, and the ebuild must generate identical metadata every time it is used.
Globally defined ebuild variables without a special meaning must similarly not rely upon variable data.
All ebuilds must define at least the following variables:
In EAPIs shown in table 8.4 as supporting sub-slots, 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, as per section 3.1.3. 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.
Ebuilds may define any of the following variables:
iuse-defaults In EAPIs shown in table 7.1 as supporting IUSE defaults, any use flag name in IUSE may be prefixed by at most one of a plus or a minus sign. If such a prefix is present, the package manager may use it as a suggestion as to the default value of the use flag if no other configuration overrides it.
EAPI | Supports PROPERTIES? | Supports REQUIRED_USE?
|
0, 1, 2, 3 | Optionally | No |
4, 5, 6 | Yes | Yes |
An empty or unset EAPI value is equivalent to 0. Ebuilds must not assume that they will get a particular one of these two values if they are expecting one of these two values.
The package manager must either pre-set the EAPI variable to 0 or ensure that it is unset before sourcing the ebuild for metadata generation. When using the ebuild for other purposes, the package manager must either pre-set EAPI to the value specified by the ebuild’s metadata or ensure that it is unset.
If any of these variables are set to invalid values, the package manager’s behaviour is undefined; ideally, an error in one ebuild should not prevent operations upon other ebuilds or packages.
If the EAPI is to be specified in an ebuild, the EAPI variable must be assigned to precisely once. The assignment must not be preceded by any lines other than blank lines or those that start with optional whitespace (spaces or tabs) followed by a # character, and the line containing the assignment statement must match the following regular expression:
The package manager must determine the EAPI of an ebuild by parsing its first non-blank and non-comment line, using the above regular expression. If it matches, the EAPI is the substring matched by the capturing parentheses (0 if empty), otherwise it is 0. For a recognised EAPI, the package manager must make sure that the EAPI value obtained by sourcing the ebuild with bash is identical to the EAPI obtained by parsing. The ebuild must be treated as invalid if these values are different.
Keywords are used to indicate levels of stability of a package on a respective architecture arch. The following conventions are used:
The -* keyword is used to indicate package versions which are not worth trying to test on unlisted architectures.
An empty KEYWORDS variable indicates uncertain functionality on any architecture.
rdepend-depend In EAPIs listed in table 7.3 as having RDEPEND=DEPEND, if RDEPEND is unset (but not if it is set to an empty string) in an ebuild, when generating metadata the package manager must treat its value as being equal to the value of DEPEND.
When dealing with eclasses, only values set in the ebuild itself are considered for this behaviour; any DEPEND or RDEPEND set in an eclass does not change the implicit RDEPEND=DEPEND for the ebuild portion, and any DEPEND value set in an eclass does not get treated as being part of RDEPEND.
The following variables must be defined by inherit (see section 10.1), and may be considered to be part of the ebuild’s metadata:
Note: Thus, by extension of section 7.1, inherit may not be used conditionally, except upon constant conditions.
The following are special variables defined by the package manager for internal use and may or may not be exported to the ebuild environment:
Note: Thus, by extension of section 7.1, phase functions must not be defined based upon any variant condition.
EAPI | Supports DEFINED_PHASES?
|
0, 1, 2, 3 | Optionally |
4, 5, 6 | Yes |
Phase function | Satisfied dependency classes
|
pkg_pretend, pkg_setup, pkg_info, pkg_nofetch | None (ebuilds can rely only on the packages in the system set) |
src_unpack, src_prepare, src_configure, src_compile, src_test, src_install | DEPEND |
pkg_preinst, pkg_postinst, pkg_prerm, pkg_postrm | RDEPEND (unless the particular dependency results in a circular dependency, in which case it may be installed later) |
pkg_config | RDEPEND, PDEPEND |
There are three classes of dependencies supported by ebuilds:
Table 8.1 lists dependencies which must be satisfied before a particular phase function is executed.
In addition, SRC_URI, HOMEPAGE, RESTRICT, PROPERTIES, LICENSE and REQUIRED_USE use dependency-style specifications to specify their values.
The following elements are recognised in at least one class of specification. All elements must be surrounded on both sides by whitespace, except at the start and end of the string.
In particular, note that whitespace is not optional.
EAPI | Supports REQUIRED_USE ?? groups?
|
0, 1, 2, 3, 4 | No |
5, 6 | Yes |
In an all-of group, all of the child elements must be matched.
In a use-conditional group, if the associated use flag is enabled (or disabled if it has an exclamation mark prefix), all of the child elements must be matched.
It is an error for a flag to be used if it is not included in IUSE_EFFECTIVE as described in section 11.1.1.
Any use-conditional group that is an immediate child of an any-of group, if not enabled (disabled for an exclamation mark prefixed use flag name), is not considered a member of the any-of group for match purposes.
In an any-of group, at least one immediate child element must be matched. A blocker is considered to be matched if its associated package dependency specification is not matched.
An empty any-of group counts as being matched.
Any use-conditional group that is an immediate child of an exactly-one-of group, if not enabled (disabled for an exclamation mark prefixed use flag name), is not considered a member of the exactly-one-of group for match purposes.
In an exactly-one-of group, exactly one immediate child element must be matched.
An empty exactly-one-of group counts as being matched.
Any use-conditional group that is an immediate child of an at-most-one-of group, if not enabled (disabled for an exclamation mark prefixed use flag name), is not considered a member of the at-most-one-of group for match purposes.
In an at-most-one-of group, at most one immediate child element must be matched.
An empty at-most-one-of group counts as being matched.
A package dependency can be in one of the following base formats. A package manager must warn or error on non-compliant input.
In EAPIs shown in table 8.4 as supporting SLOT dependencies, either of the above formats may additionally be suffixed by a :slot restriction, as described in section 8.2.6.3. A package manager must warn or error if slot dependencies are used with an EAPI not supporting SLOT dependencies.
use-deps In EAPIs shown in table 8.5 as supporting 2-style or 4-style USE dependencies, a specification may additionally be suffixed by at most one 2-style or 4-style [use] restriction, as described in section 8.2.6.4. A package manager must warn or error if this feature is used with an EAPI not supporting use dependencies.
Note: Order is important. The slot restriction must come before use dependencies.
EAPI | Supports SLOT dependencies? | Supports sub-slots?
|
0 | No | No |
1, 2, 3, 4 | Named only | No |
5, 6 | Named and operator | Yes |
EAPI | Supports USE dependencies?
|
0, 1 | No |
2, 3 | 2-style |
4, 5, 6 | 4-style |
The following operators are available:
If the specification is prefixed with one or two exclamation marks, the named dependency is a block rather than a requirement—that is to say, the specified package must not be installed, with the following exceptions:
bang-strength There are two strengths of block: weak and strong. A weak block may be ignored by the package manager, so long as any blocked package will be uninstalled later on. A strong block must not be ignored. The mapping from one or two exclamation marks to strength is described in table 8.6.
EAPI | ! | !!
|
0, 1 | Unspecified | Forbidden |
2, 3, 4, 5, 6 | Weak | Strong |
slot-deps A named slot dependency consists of a colon followed by a slot name. A specification with a named slot dependency matches only if the slot of the matched package is equal to the slot specified. If the slot of the package to match cannot be determined (e. g. because it is not a supported EAPI), the match is treated as unsuccessful.
sub-slot In EAPIs shown in table 8.4 as supporting sub-slots, a slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a / character.
slot-operator-deps An operator slot dependency consists of a colon followed by one of the following operators:
To implement the equals slot operator, the package manager will need to store the slot/sub-slot pair of the best installed version of the matching package. This syntax is only for package manager use and must not be used by ebuilds. The package manager may do this by inserting the appropriate slot/sub-slot pair between the colon and equals sign when saving the package’s dependencies. The sub-slot part must not be omitted here (when the SLOT variable omits the sub-slot part, the package is considered to have an implicit sub-slot which is equal to the regular slot).
Whenever the equals slot operator is used in an enabled dependency group, the dependencies (DEPEND) must ensure that a matching package is installed at build time. It is invalid to use the equals slot operator inside PDEPEND or inside any-of dependency specifications.
A 2-style or 4-style use dependency consists of one of the following:
Multiple requirements may be combined using commas, e. g. [first,-second,third?].
When multiple requirements are specified, all must match for a successful match.
use-dep-defaults In a 4-style use dependency, the flag name may immediately be followed by a default specified by either (+) or (-). The former indicates that, when applying the use dependency to a package that does not have the flag in question in IUSE_REFERENCEABLE, the package manager shall behave as if the flag were present and enabled; the latter, present and disabled.
Unless a 4-style default is specified, it is an error for a use dependency to be applied to an ebuild which does not have the flag in question in IUSE_REFERENCEABLE.
Note: By extension of the above, a default that could reference an ebuild using an EAPI not supporting profile IUSE injections cannot rely upon any particular behaviour for flags that would not have to be part of IUSE.
It is an error for an ebuild to use a conditional use dependency when that ebuild does not have the flag in IUSE_EFFECTIVE.
REQUIRED_USE 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).
If the package manager encounters a package version where REQUIRED_USE assertions are not met, it must treat this package version as if it was masked. No phase functions must be called.
It is an error for a flag to be used if it is not included in IUSE_EFFECTIVE.
The following tokens are permitted inside RESTRICT:
Package managers may recognise other tokens, but ebuilds may not rely upon them being supported.
The following tokens are permitted inside PROPERTIES:
Ebuilds may not rely upon any token being supported.
All filename components that are enabled (i. e. not inside a use-conditional block that is not matched) in SRC_URI must be available in the DISTDIR directory. In addition, these components are used to make the A and AA variables.
If a component contains a full URI with protocol, that download location must be used. Package managers may also consult mirrors for their files.
The special mirror:// protocol must be supported. See section 4.4.2 for mirror details.
If a simple filename rather than a full URI is provided, the package manager can only use mirrors to download the file.
The RESTRICT metadata key can be used to impose additional restrictions upon downloading—see section 8.2.8 for details.
src-uri-arrows In EAPIs supporting arrows, if an arrow is used, the filename used when saving to DISTDIR shall instead be the name on the right of the arrow. When consulting mirrors (except for those explicitly listed on the left of the arrow, if mirror:// is used), the filename to the right of the arrow shall be requested instead of the filename in the URI.
The following is a list of functions that an ebuild, or eclass, may define, and which will be called by the package manager as part of the build and/or install process. In all cases the package manager must provide a default implementation of these functions; unless otherwise stated this must be a no-op. Most functions must assume only that they have write access to the package’s working directory (the WORKDIR environment variable; see section 11.1), and the temporary directory T; exceptions are noted below. All functions may assume that they have read access to all system libraries, binaries and configuration files that are accessible to normal users.
The environment for functions run outside of the build sequence (that is, pkg_config, pkg_info, pkg_prerm and pkg_postrm) must be the environment used for the build of the package, not the current configuration.
Ebuilds must not call nor assume the existence of any phase functions.
Some functions may assume that their initial working directory is set to a particular location; these are noted below. If no initial working directory is mandated, it may be set to anything and the ebuild must not rely upon a particular location for it. The ebuild may assume that the initial working directory for any phase is a trusted location that may only be written to by a privileged user and group.
s-workdir-fallback Some functions are described as having an initial working directory of S with an error or fallback to WORKDIR. For EAPIs listed in table 9.1 as having the fallback, this means that if S is not a directory before the start of the phase function, the initial working directory shall be WORKDIR instead. For EAPIs where it is a conditional error, if S is not a directory before the start of the phase function, it is a fatal error, unless all of the following conditions are true, in which case the fallback to WORKDIR is used:
EAPI | Fallback to WORKDIR permitted?
|
0, 1, 2, 3 | Always |
4, 5, 6 | Conditional error |
pkg-pretend The pkg_pretend function is only called for EAPIs listed in table 9.2 as supporting it.
The pkg_pretend function may be used to carry out sanity checks early on in the install process. For example, if an ebuild requires a particular kernel configuration, it may perform that check in pkg_pretend and call eerror and then die with appropriate messages if the requirement is not met.
pkg_pretend is run separately from the main phase function sequence, and does not participate in any kind of environment saving. There is no guarantee that any of an ebuild’s dependencies will be met at this stage, and no guarantee that the system state will not have changed substantially before the next phase is executed.
pkg_pretend must not write to the filesystem.
The pkg_setup function sets up the ebuild’s environment for all following functions, before the build process starts. Further, it checks whether any necessary prerequisites not covered by the package manager, e. g. that certain kernel configuration options are fulfilled.
pkg_setup must be run with full filesystem permissions, including the ability to add new users and/or groups to the system.
The src_unpack function extracts all of the package’s sources. In EAPIs lacking src_prepare, it may also apply patches and set up the package’s build system for further use.
The initial working directory must be WORKDIR, and the default implementation used when the ebuild lacks the src_unpack function shall behave as:
src-prepare The src_prepare function is only called for EAPIs listed in table 9.3 as supporting it. The src_prepare function can be used for post-unpack source preparation.
The initial working directory is S, with an error or fallback to WORKDIR as discussed in section 9.1.1.
src-prepare-6 For EAPIs listed in table 9.3 as using format 6, the default implementation used when the ebuild lacks the src_prepare function shall behave as:
For other EAPIs supporting src_prepare, the default implementation used when the ebuild lacks the src_prepare function is a no-op.
EAPI | Supports src_prepare? | Format
|
0, 1 | No | Not applicable |
2, 3, 4, 5 | Yes | no-op |
6 | Yes | 6 |
src-configure The src_configure function is only called for EAPIs listed in table 9.4 as supporting it.
The initial working directory is S, with an error or fallback to WORKDIR as discussed in section 9.1.1.
The src_configure function configures the package’s build environment. The default implementation used when the ebuild lacks the src_configure function shall behave as:
src-compile The src_compile function configures the package’s build environment in EAPIs lacking src_configure, and builds the package in all EAPIs.
The initial working directory is S, with an error or fallback to WORKDIR as discussed in section 9.1.1.
src-compile-0 For EAPIs listed in table 9.5 as using format 0, the default implementation used when the ebuild lacks the src_compile function shall behave as:
src-compile-1 For EAPIs listed in table 9.5 as using format 1, the default implementation used when the ebuild lacks the src_compile function shall behave as:
src-compile-2 For EAPIs listed in table 9.5 as using format 2, the default implementation used when the ebuild lacks the src_compile function shall behave as:
The src_test function runs unit tests for the newly built but not yet installed package as provided.
The initial working directory must be S if that exists, falling back to WORKDIR otherwise. The default implementation used when the ebuild lacks the src_test function must, if tests are enabled, run emake check if and only if such a target is available, or if not run emake test if and only if such a target is available. In both cases, if emake returns non-zero the build must be aborted.
parallel-tests For EAPIs listed in table 9.6 as not supporting parallel tests, the emake command must be called with option -j1.
The src_test function may be disabled by RESTRICT. See section 8.2.8. It may be disabled by user too, using a PM-specific mechanism.
src-install The src_install function installs the package’s content to a directory specified in D.
The initial working directory is S, with an error or fallback to WORKDIR as discussed in section 9.1.1.
src-install-4 For EAPIs listed in table 9.7 as using format 4, the default implementation used when the ebuild lacks the src_install function shall behave as:
src-install-6 For EAPIs listed in table 9.7 as using format 6, the default implementation used when the ebuild lacks the src_install function shall behave as:
For other EAPIs, the default implementation used when the ebuild lacks the src_install function is a no-op.
The pkg_preinst function performs any special tasks that are required immediately before merging the package to the live filesystem. It must not write outside of the directories specified by the ROOT and D environment variables.
pkg_preinst must be run with full access to all files and directories below that specified by the ROOT and D environment variables.
The pkg_postinst function performs any special tasks that are required immediately after merging the package to the live filesystem. It must not write outside of the directory specified in the ROOT environment variable.
pkg_postinst, like, pkg_preinst, must be run with full access to all files and directories below that specified by the ROOT environment variable.
The pkg_prerm function performs any special tasks that are required immediately before unmerging the package from the live filesystem. It must not write outside of the directory specified by the ROOT environment variable.
pkg_prerm must be run with full access to all files and directories below that specified by the ROOT environment variable.
The pkg_postrm function performs any special tasks that are required immediately after unmerging the package from the live filesystem. It must not write outside of the directory specified by the ROOT environment variable.
pkg_postrm must be run with full access to all files and directories below that specified by the ROOT environment variable.
The pkg_config function performs any custom steps required to configure a package after it has been fully installed. It is the only ebuild function which may be interactive and prompt for user input.
pkg_config must be run with full access to all files and directories inside of ROOT.
pkg-info The pkg_info function may be called by the package manager when displaying information about an installed package. In EAPIs listed in table 9.8 as supporting pkg_info on non-installed packages, it may also be called by the package manager when displaying information about a non-installed package. In this case, ebuild authors should note that dependencies may not be installed.
pkg_info must not write to the filesystem.
EAPI | Supports pkg_info on non-installed packages?
|
0, 1, 2, 3 | No |
4, 5, 6 | Yes |
The pkg_nofetch function is run when the fetch phase of an fetch-restricted ebuild is run, and the relevant source files are not available. It should direct the user to download all relevant source files from their respective locations, with notes concerning licensing if applicable.
pkg_nofetch must require no write access to any part of the filesystem.
default-phase-funcs In EAPIs listed in table 9.9 as supporting default_ phase functions, a function named default_(phase) that behaves as the default implementation for that EAPI shall be defined when executing any ebuild phase listed in the table. Ebuilds must not call these functions except when in the phase in question.
EAPI | Supports default_ functions in phases
|
0, 1 | None |
2, 3 | pkg_nofetch, src_unpack, src_prepare, src_configure, src_compile, src_test |
4, 5, 6 | pkg_nofetch, src_unpack, src_prepare, src_configure, src_compile, src_install, src_test |
The call order for installing a package is:
The call order for uninstalling a package is:
The call order for upgrading, downgrading or reinstalling a package is:
Note: When up- or downgrading a package in EAPI 0 or 1, the last four phase functions can alternatively be called in the order pkg_preinst, pkg_postinst, pkg_prerm, pkg_postrm. This behaviour is deprecated.
The pkg_config, pkg_info and pkg_nofetch functions are not called in a normal sequence. The pkg_pretend function is called some unspecified time before a (possibly hypothetical) normal sequence.
For installing binary packages, the src phases are not called.
When building binary packages that are not to be installed locally, the pkg_preinst and pkg_postinst functions are not called.
Eclasses serve to store common code that is used by more than one ebuild, which greatly aids maintainability and reduces the tree size. However, due to metadata cache issues, care must be taken in their use. In format they are similar to an ebuild, and indeed are sourced as part of any ebuild using them. The interpreter is therefore the same, and the same requirements for being parseable hold.
Eclasses must be located in the eclass directory in the top level of the repository—see section 4.6. Each eclass is a single file named <name>.eclass, where <name> is the name of this eclass, used by inherit and EXPORT_FUNCTIONS among other places.
An ebuild wishing to make use of an eclass does so by using the inherit command in global scope. This will cause the eclass to be sourced as part of the ebuild—any function or variable definitions in the eclass will appear as part of the ebuild, with exceptions for certain metadata variables, as described below.
The inherit command takes one or more parameters, which must be the names of eclasses (excluding the .eclass suffix and the path). For each parameter, in order, the named eclass is sourced.
Eclasses may end up being sourced multiple times.
The inherit command must also ensure that:
The IUSE, REQUIRED_USE, DEPEND, RDEPEND and PDEPEND variables are handled specially when set by an eclass. They must be accumulated across eclasses, appending the value set by each eclass to the resulting value after the previous one is loaded. Then the eclass-defined value is appended to that defined by the ebuild. In the case of RDEPEND, this is done after the implicit RDEPEND rules in section 7.3.3 are applied.
There is one command available in the eclass environment that is neither available nor meaningful in ebuilds—EXPORT_FUNCTIONS. This can be used to alias ebuild phase functions from the eclass so that an ebuild inherits a default definition whilst retaining the ability to override and call the eclass-defined version from it. The use of it is best illustrated by an example; this is given in listing 10.1 and is a snippet from a hypothetical foo.eclass.
This example defines an eclass src_compile function and uses EXPORT_FUNCTIONS to alias it. Then any ebuild that inherits foo.eclass will have a default src_compile defined, but should the author wish to override it he can access the function in foo.eclass by calling foo_src_compile.
EXPORT_FUNCTIONS must only be used on ebuild phase functions. The function that is aliased must be named eclassname_phasefunctionname, where eclassname is the name of the eclass.
The package manager must define the following environment variables. Not all variables are meaningful in all phases; variables that are not meaningful in a given phase may be unset or set to any value. Ebuilds must not attempt to modify any of these variables, unless otherwise specified.
Because of their special meanings, these variables may not be preserved consistently across all phases as would normally happen due to environment saving (see 11.2). For example, EBUILD_PHASE is different for every phase, and ROOT may have changed between the various different pkg_* phases. Ebuilds must recalculate any variable they derive from an inconsistent variable.
Table 11.1: Defined variables | |||
Variable | Legal in | Consistent? | Description
|
P |
All | No2 |
Package name and version, without the revision part. For example, vim-7.0.174. |
PF |
All | Ditto |
Package name, version, and revision (if any), for example vim-7.0.174-r1. |
PN |
All | Ditto |
Package name, for example vim. |
CATEGORY |
All | Ditto |
The package’s category, for example app-editors. |
PV |
All | Yes |
Package version, with no revision. For example 7.0.174. |
PR |
All | Yes |
Package revision, or r0 if none exists. |
PVR |
All | Yes |
Package version and revision (if any), for example 7.0.174 or 7.0.174-r1. |
A |
src_*, pkg_nofetch | Yes |
All source files available for the package, whitespace separated with no leading or trailing whitespace, and in the order in which the item first appears in a matched component of SRC_URI. Does not include any that are disabled because of USE conditionals. The value is calculated from the base names of each element of the SRC_URI ebuild metadata variable. |
AA3 |
Ditto | Yes |
aa All source files that could be available for the package, including any that are disabled in A because of USE conditionals. The value is calculated from the base names of each element of the SRC_URI ebuild metadata variable. Only for EAPIs listed in table 11.3 as supporting AA. |
FILESDIR |
src_*, global scope4 | Yes |
The full path to a directory where the files from the package’s files directory (used for small support files or patches) are available. See section 4.3. May or may not exist; if a repository provides no support files for the package in question then an ebuild must be prepared for the situation where FILESDIR points to a non-existent directory. |
DISTDIR |
Ditto | Yes |
The full path to the directory in which the files in the A variable are stored. |
WORKDIR |
Ditto | Yes |
The full path to the ebuild’s working directory, where all build data should be contained. |
S |
src_* | Yes |
The full path to the temporary build directory, used by src_compile, src_install etc. Defaults to ${WORKDIR}/${P}. May be modified by ebuilds. If S is assigned in the global scope of an ebuild, then the restrictions of section 11.2 for global variables apply. |
PORTDIR |
src_* | No |
The full path to the master repository’s base directory. |
ECLASSDIR |
src_* | No |
The full path to the master repository’s eclass directory. |
ROOT |
pkg_* | No |
The absolute path to the root directory into which the package is to be merged. Phases which run with full filesystem access must not touch any files outside of the directory given in ROOT. Also of note is that in a cross-compiling environment, binaries inside of ROOT will not be executable on the build machine, so ebuilds must not call them. ROOT must be non-empty and end in a trailing slash. |
EROOT |
pkg_* | No |
Contains the path ${ROOT%/}${EPREFIX}/ for convenience. See also the EPREFIX variable. Only for EAPIs listed in table 11.4 as supporting EROOT. |
T |
All | Partially5 |
The full path to a temporary directory for use by the ebuild. |
TMPDIR |
All | Ditto |
Must be set to the location of a usable temporary directory, for any applications called by an ebuild. Must not be used by ebuilds directly; see T above. |
HOME |
All | Ditto |
The full path to an appropriate temporary directory for use by any programs invoked by the ebuild that may read or modify the home directory. |
EPREFIX |
All | Yes |
The normalised offset-prefix path of an offset installation. When EPREFIX is not set in the calling environment, EPREFIX defaults to the built-in offset-prefix that was set during installation of the package manager. When a different EPREFIX value than the built-in value is set in the calling environment, a cross-prefix build is performed where using the existing utilities, a package is built for the given EPREFIX, akin to ROOT. See also 11.1.3. Only for EAPIs listed in table 11.4 as supporting EPREFIX. |
D |
src_install | No |
Contains the full path to the image directory into which the package should be installed. Must be non-empty and end in a trailing slash. |
D (continued) |
pkg_preinst, pkg_postinst | Yes |
Contains the full path to the image that is about to be or has just been merged. Must be non-empty and end in a trailing slash. |
ED |
src_install, pkg_preinst, pkg_postinst | See D |
Contains the path ${D%/}${EPREFIX}/ for convenience. See also the EPREFIX variable. Only for EAPIs listed in table 11.4 as supporting ED. |
DESTTREE |
src_install | No |
Controls the location where dobin, dolib, domo, and dosbin install things. |
INSDESTTREE |
src_install | No |
Controls the location where doins installs things. |
USE |
All | Yes |
A whitespace-delimited list of all active USE flags for this ebuild. See section 11.1.1 for details. |
EBUILD_PHASE |
All | No |
Takes one of the values config, setup, nofetch, unpack, prepare, configure, compile, test, install, preinst, postinst, prerm, postrm, info, pretend according to the top level ebuild function that was executed by the package manager. May be unset or any single word that is not any of the above when the ebuild is being sourced for other (e. g. metadata or QA) purposes. |
EBUILD_PHASE_FUNC |
All | No |
ebuild-phase-func Takes one of the values pkg_config, pkg_setup, pkg_nofetch, src_unpack, src_prepare, src_configure, src_compile, src_test, src_install, pkg_preinst, pkg_postinst, pkg_prerm, pkg_postrm, pkg_info, pkg_pretend according to the top level ebuild function that was executed by the package manager. May be unset or any single word that is not any of the above when the ebuild is being sourced for other (e. g. metadata or QA) purposes. Only for EAPIs listed in table 11.2 as supporting EBUILD_PHASE_FUNC. |
KV |
All | Yes |
kv The version of the running kernel at the time the ebuild was first executed, as returned by the uname -r command or equivalent. May be modified by ebuilds. Only for EAPIs listed in table 11.3 as supporting KV. |
MERGE_TYPE |
pkg_* | No |
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, and buildonly if building a binary package without installing it. Only for EAPIs listed in table 11.2 as supporting MERGE_TYPE. |
REPLACING_VERSIONS |
pkg_* (see text) | Yes |
A list of all versions of this package (including revision, if specified), whitespace separated with no leading or trailing whitespace, that are being replaced (uninstalled or overwritten) as a result of this install. See section 11.1.2. Only for EAPIs listed in table 11.2 as supporting REPLACING_VERSIONS. |
REPLACED_BY_VERSION |
pkg_prerm, pkg_postrm | Yes |
The single version of this package (including revision, if specified) that is replacing us, if we are being uninstalled as part of an install, or an empty string otherwise. See section 11.1.2. Only for EAPIs listed in table 11.2 as supporting REPLACED_BY_VERSION. |
EAPI | MERGE_TYPE? | REPLACING_VERSIONS? | REPLACED_BY_VERSION? | EBUILD_PHASE_FUNC?
|
0, 1, 2, 3 | No | No | No | No |
4 | Yes | Yes | Yes | No |
5, 6 | Yes | Yes | Yes | Yes |
EAPI | AA? | KV?
|
0, 1, 2, 3 | Yes | Yes |
4, 5, 6 | No | No |
EAPI | EPREFIX? | EROOT? | ED?
|
0, 1, 2 | No | No | No |
3, 4, 5, 6 | Yes | Yes | Yes |
Except where otherwise noted, all variables set in the active profiles’ make.defaults files must be exported to the ebuild environment. CHOST, CBUILD and CTARGET, if not set by profiles, must contain either an appropriate machine tuple (the definition of appropriate is beyond the scope of this specification) or be unset.
PATH must be initialized by the package manager to a “usable” default. The exact value here is left up to interpretation, but it should include the equivalent “sbin” and “bin” and any package manager specific directories.
GZIP, BZIP, BZIP2, CDPATH, GREP_OPTIONS, GREP_COLOR and GLOBIGNORE must not be set.
locale-settings The package manager must ensure that the LC_CTYPE and LC_COLLATE locale categories are equivalent to the POSIX locale, as far as characters in the ASCII range (U+0000 to U+007F) are concerned. Only for EAPIs listed in such a manner in table 11.5.
EAPI | Sane LC_CTYPE and LC_COLLATE?
|
0, 1, 2, 3, 4, 5 | Undefined |
6 | Yes |
This section discusses the handling of four variables:
In all cases, the values of IUSE_REFERENCEABLE and IUSE_EFFECTIVE are undefined during metadata generation.
For EAPIs listed in table 5.2 as not supporting profile defined IUSE injection, IUSE_REFERENCEABLE is equal to the calculated IUSE value. For EAPIs where profile defined IUSE injection is supported, IUSE_REFERENCEABLE is equal to IUSE_EFFECTIVE.
For EAPIs listed in table 5.2 as not supporting profile defined IUSE injection, IUSE_EFFECTIVE contains the following values:
profile-iuse-inject For EAPIs listed in table 5.2 as supporting profile defined IUSE injection, IUSE_EFFECTIVE contains the following values:
The USE variable is set by the package manager. For each value in IUSE_EFFECTIVE, USE shall contain that value if the flag is to be enabled for the ebuild in question, and shall not contain that value if it is to be disabled. In EAPIs listed in table 5.2 as not supporting profile defined IUSE injection, USE may contain other flag names that are not relevant for the ebuild.
For EAPIs listed in table 5.2 as supporting profile defined IUSE injection, the variables named in USE_EXPAND and USE_EXPAND_UNPREFIXED shall have their profile-provided values reduced to contain only those values that are present in IUSE_EFFECTIVE.
For EAPIs listed in table 5.2 as supporting profile defined IUSE injection, the package manager must save the calculated value of IUSE_EFFECTIVE when installing a package. Details are beyond the scope of this specification.
replace-version-vars In EAPIs listed in table 11.2 as supporting it, the REPLACING_VERSIONS variable shall be defined in pkg_preinst and pkg_postinst. In addition, it may be defined in pkg_pretend and pkg_setup, although ebuild authors should take care to handle binary package creation and installation correctly when using it in these phases.
REPLACING_VERSIONS 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.
In EAPIs listed in table 11.2 as supporting it, the REPLACED_BY_VERSION variable shall be defined in pkg_prerm and pkg_postrm. It shall contain at most one value.
offset-prefix-vars Table 11.6 lists the EAPIs which support offset-prefix installations. This support was initially added in EAPI 3, in the form of three extra variables. Two of these, EROOT and ED, are convenience variables using the variable EPREFIX. In EAPIs that do not support an offset-prefix, the installation offset is hardwired to /usr. In offset-prefix supporting EAPIs the installation offset is set as ${EPREFIX}/usr and hence can be adjusted using the variable EPREFIX. Note that the behaviour of offset-prefix aware and agnostic is the same when EPREFIX is set to the empty string in offset-prefix aware EAPIs. The latter do have the variables ED and EROOT properly set, though.
Exported and default scope variables are saved between functions. A non-local variable set in a function earlier in the call sequence must have its value preserved for later functions, including functions executed as part of a later uninstall.
Note: pkg_pretend is not part of the normal call sequence, and does not take part in environment saving.
Variables that were exported must remain exported in later functions; variables with default visibility may retain default visibility or be exported.
Variables with special meanings to the package manager are excluded from this rule.
Global variables must only contain invariant values (see 7.1). If a global variable’s value is invariant, it may have the value that would be generated at any given point in the build sequence.
This is demonstrated by code listing 11.1.
This section documents the commands available to an ebuild. Unless otherwise specified, they may be aliases, shell functions, or executables in the ebuild’s PATH.
When an ebuild is being sourced for metadata querying rather than for a build (that is to say, when none of the src_ or pkg_ functions are to be called), no external command may be executed. The package manager may take steps to enforce this.
Any ebuild not listed in the system set for the active profile(s) may assume the presence of every command that is always provided by the system set for that profile. However, it must target the lowest common denominator of all systems on which it might be installed—in most cases this means that the only packages that can be assumed to be present are those listed in the base profile or equivalent, which is inherited by all available profiles. If an ebuild requires any applications not provided by the system profile, or that are provided conditionally based on USE flags, appropriate dependencies must be used to ensure their presence.
The following commands must always be available in the ebuild environment:
failglob For EAPIs listed such in table 11.7, 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 | GNU find? | failglob in global scope?
|
0, 1, 2, 3, 4 | Undefined | No |
5 | Yes | No |
6 | Yes | Yes |
In some cases a package’s build process will require the availability of executables not provided by the core system, a common example being autotools. The availability of commands provided by the particular types of dependencies is explained in section 8.1.
The following commands will always be available in the ebuild environment, provided by the package manager. Except where otherwise noted, they may be internal (shell functions or aliases) or external commands available in PATH; where this is not specified, ebuilds may not rely upon either behaviour.
Unless otherwise noted, any output of these commands ends with a newline.
die-on-failure Where a command is listed as having EAPI dependent failure behaviour, a failure shall either result in a non-zero exit status or abort the build process, as determined by table 11.8.
The following commands affect this behaviour:
Explicit die or assert commands only respect nonfatal when called with the -n option and in EAPIs supporting this option, see table 11.11.
EAPI | Command failure behaviour | Supports nonfatal?
|
0, 1, 2, 3 | Non-zero exit | No |
4, 5, 6 | Aborts | Yes |
banned-commands Some commands are banned in some EAPIs. If a banned command is called, the package manager must abort the build process indicating an error.
EAPI | Command banned? | ||
dohard | dosed | einstall
| |
0, 1, 2, 3 | No | No | No |
4, 5 | Yes | Yes | No |
6 | Yes | Yes | Yes |
These commands affect the behaviour of the sandbox. Each command takes a single directory as argument. Ebuilds must not run any of these commands once the current phase function has returned.
These commands are used to extract information about the system. Ebuilds must not run any of these commands in parallel with any other package manager command. Ebuilds must not run any of these commands once the current phase function has returned.
host-root-option In EAPIs listed in table 11.10 as supporting option --host-root, this flag as the first argument will cause the query to apply to the host root instead of ROOT.
EAPI | *_version supports --host-root?
|
0, 1, 2, 3, 4 | No |
5, 6 | Yes |
These commands display messages to the user. Unless otherwise stated, the entire argument list is used as a message, with backslash-escaped characters interpreted as for the echo -e command of bash, notably \t for a horizontal tab, \n for a new line, and \\ for a literal backslash. Ebuilds must not run any of these commands once the current phase function has returned. Unless otherwise noted, output may be sent to stdout, stderr or some other appropriate facility.
These commands are used when an error is detected that will prevent the build process from completing. Ebuilds must not run any of these commands once the current phase function has returned.
EAPI | die and assert support -n?
|
0, 1, 2, 3, 4, 5 | No |
6 | Yes |
These commands are used during the src_prepare phase to apply patches to the package’s sources. Ebuilds must not run any of these commands once the current phase function has returned.
These commands are used during the src_configure, src_compile, and src_install phases to run the package’s build commands. Ebuilds must not run any of these commands once the current phase function has returned.
econf-options econf must pass the following options to the configure script:
EAPI | --disable-dependency-tracking | --disable-silent-rules | --docdir | --htmldir
|
0, 1, 2, 3 | No | No | No | No |
4 | Yes | No | No | No |
5 | Yes | Yes | No | No |
6 | Yes | Yes | Yes | Yes |
Note that the ${EPREFIX} component represents the same offset-prefix as described in Table 11.1. It facilitates offset-prefix installations which is supported by EAPIs listed in Table 11.4. When no offset-prefix installation is in effect, EPREFIX becomes the empty string, making the behaviour of econf equal for both offset-prefix supporting and agnostic EAPIs.
econf must be implemented internally—that is, as a bash function and not an external script. Should any portion of it fail, it must abort the build using die, unless run using nonfatal, in which case it must return non-zero exit status.
The variable ED is defined as in Table 11.1 and depends on the use of an offset-prefix. When such offset-prefix is absent, ED is equivalent to D. ED is always available in EAPIs that support offset-prefix installations as listed in Table 11.4, hence EAPIs lacking offset-prefix support should use D instead of ED in the command given in Listing 11.2. Variable libdir is an auxiliary local variable whose value is determined by Algorithm 11.3.
These commands are used to install files into the staging area, in cases where the package’s make install target cannot be used or does not install all needed files. Except where otherwise stated, all filenames created or modified are relative to the staging directory including the offset-prefix ED in offset-prefix aware EAPIs, or just the staging directory D in offset-prefix agnostic EAPIs. Existing destination files are overwritten. These commands must all be external programs and not bash functions or aliases—that is, they must be callable from xargs. Calling any of these commands without a filename parameter is an error. Ebuilds must not run any of these commands once the current phase function has returned.
Failure behaviour is EAPI dependent as per section 11.3.3.1.
It is undefined whether a failure shall occur if -r is not specified and a directory is encountered. Ebuilds must not rely upon any particular behaviour.
doman-langs In EAPIs listed in table 11.17 as supporting language detection by filename, a man page with name of the form foo.lang.1 shall go to /usr/share/man/lang/man1/foo.1, where lang refers to a pair of lower-case ASCII letters optionally followed by an underscore and a pair of upper-case ASCII letters. Failure behaviour is EAPI dependent as per section 11.3.3.1.
With option -i18n=lang, a man page shall be installed into an appropriate subdirectory of /usr/share/man/lang (e. g. /usr/share/man/lang/man1/foo.pl.1 would be the destination for foo.pl.1). The lang subdirectory level is skipped if lang is the empty string. In EAPIs specified by table 11.17, the -i18n option takes precedence over the language code in the filename.
EAPI | Supports doheader and newheader?
|
0, 1, 2, 3, 4 | No |
5, 6 | Yes |
EAPI | doins supports symlinks?
|
0, 1, 2, 3 | No |
4, 5, 6 | Yes |
EAPI | Language detection by filename? | Option -i18n takes precedence?
|
0, 1 | No | Not applicable |
2, 3 | Yes | No |
4, 5, 6 | Yes | Yes |
EAPI | new* can read from stdin?
|
0, 1, 2, 3, 4 | No |
5, 6 | Yes |
The following commands are used to set the various destination trees, all relative to ${ED} in offset-prefix aware EAPIs and relative to ${D} in offset-prefix agnostic EAPIs, used by the above installation commands. They must be shell functions or aliases, due to the need to set variables read by the above commands. Ebuilds must not run any of these commands once the current phase function has returned.
docompress In EAPIs listed in table 11.19 as supporting controllable compression, the package manager may optionally compress a subset of the files under the ED directory. To control which directories may or may not be compressed, the package manager shall maintain two lists:
The optional compression shall be carried out after src_install has completed, and before the execution of any subsequent phase function. For each item in the inclusion list, pretend it has the value of the ED variable prepended, then:
Whether an item is to be excluded is determined as follows: For each item in the exclusion list, pretend it has the value of the ED variable prepended, then:
The package manager shall take appropriate steps to ensure that its compression mechanisms behave sensibly even if an item is listed in the inclusion list multiple times, if an item is a symlink, or if a file is already compressed.
The following commands may be used in src_install to alter these lists. It is an error to call any of these functions from any other phase.
EAPI | Supports controllable compression? | Supports docompress?
|
0, 1, 2, 3 | No | No |
4, 5, 6 | Yes | Yes |
These functions provide behaviour based upon set or unset use flags. Ebuilds must not run any of these commands once the current phase function has returned. It is an error if an ebuild calls any of these functions in global scope.
Unless otherwise noted, if any of these functions is called with a flag value that is not included in IUSE_EFFECTIVE, either behaviour is undefined or it is an error as decided by table 11.20.
EAPI | Behaviour
|
0, 1, 2, 3 | Undefined |
4, 5, 6 | Error |
EAPI | Supports empty third argument?
|
0, 1, 2, 3 | No |
4, 5, 6 | Yes |
EAPI | usex? | in_iuse?
|
0, 1, 2, 3, 4 | No | No |
5 | Yes | No |
6 | Yes | Yes |
These functions check whitespace-separated lists for a particular value.
The following commands are always available in the ebuild environment, but don’t really fit in any of the above categories. Ebuilds must not run any of these commands once the current phase function has returned.
Arguments to unpack are interpreted as follows:
Any unrecognised file format shall be skipped silently. If unpacking a supported file format fails, unpack shall abort the build process.
unpack-extensions Must be able to unpack the following file formats, if the relevant binaries are available:
It is up to the ebuild to ensure that the relevant external utilities are available, whether by being in the system set or via dependencies.
unpack-ignore-case unpack matches filename extensions in a case-insensitive manner, for EAPIs listed such in table 11.23.
EAPI | Supports absolute and relative paths? | Case-insensitive matching?
|
0, 1, 2, 3, 4, 5 | No | No |
6 | Yes | Yes |
EAPI | default? | einstalldocs? | get_libdir?
|
0, 1 | No | No | No |
2, 3, 4, 5 | Yes | No | No |
6 | Yes | Yes | Yes |
The following commands are available for debugging. Normally all of these commands should be no ops; a package manager may provide a special debug mode where these commands instead do something. Ebuilds must not run any of these commands once the current phase function has returned.
Except where documented otherwise, all functions and variables that contain any of the following strings (ignoring case) are reserved for package manager use and may not be used or relied upon by ebuilds:
For the sake of this section:
The following exclusivity and invariancy requirements are mandated:
Note: In this chapter, file and regular file have their Unix meanings.
The merge process merges the contents of the D directory onto the filesystem under ROOT. This is not a straight copy; there are various subtleties which must be addressed.
The unmerge process removes an installed package’s files. It is not covered in detail in this specification.
Directories are merged recursively onto the filesystem. The method used to perform the merge is not specified, so long as the end result is correct. In particular, merging a directory may alter or remove the source directory under D.
Ebuilds must not attempt to merge a directory on top of any existing file that is not either a directory or a symlink to a directory.
The owner, group and mode (including set*id and sticky bits) of the directory must be preserved, except as follows:
On SELinux systems, the SELinux context must also be preserved. Other directory attributes, including modification time, may be discarded.
Behaviour upon encountering an empty directory is undefined. Ebuilds must not attempt to install an empty directory.
Regular files are merged onto the filesystem (but see the notes on configuration file protection, below). The method used to perform the merge is not specified, so long as the end result is correct. In particular, merging a regular file may alter or remove the source file under D.
Ebuilds must not attempt to merge a regular file on top of any existing file that is not either a regular file or a symlink to a regular file.
The owner, group and mode (including set*id and sticky bits) of the file must be preserved, except as follows:
On SELinux systems, the SELinux context must also be preserved. Other file attributes may be discarded.
mtime-preserve In EAPIs listed in table 12.1, the package manager must preserve modification times of regular files. This includes files being compressed before merging. Exceptions to this are files newly created by the package manager and binary object files being stripped of symbols.
When preserving, the seconds part of every regular file’s mtime must be preserved exactly. The sub-second part must either be set to zero, or set to the greatest value supported by the operating system and filesystem that is not greater than the sub-second part of the original time.
For any given destination filesystem, the package manager must ensure that for any two preserved files a, b in that filesystem the relation mtime(a) ≤ mtime(b) still holds, if it held under the original image directory.
In other EAPIs, the behaviour with respect to file modification times is undefined.
EAPI | mtimes preserved?
|
0, 1, 2 | Undefined |
3, 4, 5, 6 | Yes |
The package manager must provide a means to prevent user configuration files from being overwritten by any package updates. The profile variables CONFIG_PROTECT and CONFIG_PROTECT_MASK (section 5.3) control the paths for which this must be enforced.
In order to ensure interoperability with configuration update tools, the following scheme must be used by all package managers when merging any regular file:
Symlinks are merged as symlinks onto the filesystem. The link destination for a merged link shall be the same as the link destination for the link under D, except as noted below. The method used to perform the merge is not specified, so long as the end result is correct; in particular, merging a symlink may alter or remove the symlink under D.
Ebuilds must not attempt to merge a symlink on top of a directory.
Any absolute symlink whose link starts with D must be rewritten with the leading D removed. The package manager should issue a notice when doing this.
A hard link may be merged either as a single file with links or as multiple independent files.
Ebuilds must not attempt to install any other type of file (FIFOs, device nodes etc).
The profiles/metadata/cache directory, if it exists, contains directories whose names are the same as categories in the repository. Each subdirectory may optionally contain one file per package version in that category, named <package>-<version>, in the format described below.
The metadata cache may be incomplete or non-existent, and may contain additional bogus entries.
Each cache file contains the textual values of various metadata keys, one per line, in the following order. Other lines may be present following these; their meanings are not defined here.
Future EAPIs may define new variables, remove existing variables, change the line number or format used for a particular variable, add or reduce the total length of the file and so on. Any future EAPI that uses this cache format will continue to place the EAPI value on line 15 if such a concept makes sense for that EAPI, and will place a value that is clearly not a supported EAPI on line 15 if it does not.
This section contains explanations of some of the terms used in this document whose meaning may not be immediately obvious.
[1] Michał Górny. GLEP 68: Package and category metadata. https://wiki.gentoo.org/wiki/GLEP:68, April 2016.
[2] Marius Mauch. GLEP 44: Manifest2 format. https://wiki.gentoo.org/wiki/GLEP:44, December 2005.
[3] Jason Stubbs. GLEP 37: Virtuals deprecation. https://wiki.gentoo.org/wiki/GLEP:37, April 2005.
The metadata.xml file is used to contain extra package- or category-level information beyond what is stored in ebuild metadata. Its exact format is strictly beyond the scope of this document, and is described in GLEP 68 [1].
The following items are not specified by this document, and must not be relied upon by ebuilds. This is, of course, an incomplete list—it covers only the things that the authors know have been abused in the past.
The items described in this chapter are included for information only. Unless otherwise noted, they were deprecated or abandoned long before EAPI was introduced. Ebuilds must not use these features, and package managers should not be changed to support them.
Historically, Portage supported if-else use conditionals, as shown by listing C.1. The block before the colon would be taken if the condition was met, and the block after the colon would be taken if the condition was not met.
Portage has very crude support for CVS packages. The package foo could contain a file named foo-cvs.1.2.3.ebuild. This version would order higher than any non-CVS version (including foo-2.ebuild). This feature has not seen real world use and breaks versioned dependencies, so it must not be used.
The use.defaults file in the profile directory was used to implement ‘autouse’—switching USE flags on or off depending upon which packages are installed. It was deprecated long ago and finally removed in 2009.
Historically, virtuals were special packages rather than regular ebuilds. An ebuild could specify in the PROVIDE metadata that it supplied certain virtuals, and the package manager had to bear this in mind when handling dependencies.
Old-style virtuals were supported by EAPIs 0, 1, 2, 3 and 4, and were phased out via GLEP 37 [3].
Note: This chapter is informative and for convenience only. Refer to the main text for specifics. For lack of space, EAPIs 0, 1, and 2 have been consolidated into a single column in the table below; entries marked with an asterisk differ between these EAPIs. See the 2012-09-20 edition of this document for a complete table of previous EAPIs.
Table D.1: Features in EAPIs | ||||||
Feature | Reference | EAPIs | ||||
0, 1, 2 | 3 | 4 | 5 | 6
| ||
Stable use masking/forcing | stablemask p64 |
No |
No |
No |
Yes |
Yes |
Bash version | bash-version p78 |
3.2 |
3.2 |
3.2 |
3.2 |
4.2 |
IUSE defaults | iuse-defaults p85 |
* |
Yes |
Yes |
Yes |
Yes |
REQUIRED_USE | required-use p85 |
No |
No |
Yes |
Yes |
Yes |
PROPERTIES | properties p85 |
Optionally |
Optionally |
Yes |
Yes |
Yes |
RDEPEND=DEPEND | rdepend-depend p92 |
Yes |
Yes |
No |
No |
No |
DEFINED_PHASES | defined-phases p96 |
Optionally |
Optionally |
Yes |
Yes |
Yes |
?? ( ) groups | at-most-one-of p106 |
No |
No |
No |
Yes |
Yes |
SRC_URI arrows | src-uri-arrows p125 |
* |
Yes |
Yes |
Yes |
Yes |
Slot dependencies | slot-deps p122 |
* |
Named |
Named |
Named and Operator |
Named and Operator |
Sub-slots | sub-slot p122 |
No |
No |
No |
Yes |
Yes |
Use dependencies | use-deps p113 |
* |
2-style |
4-style |
4-style |
4-style |
! blockers | bang-strength p119 |
* |
Weak |
Weak |
Weak |
Weak |
!! blockers | bang-strength p119 |
* |
Strong |
Strong |
Strong |
Strong |
S to WORKDIR fallback | s-workdir-fallback p128 |
Always |
Always |
Conditional |
Conditional |
Conditional |
pkg_pretend | pkg-pretend p131 |
No |
No |
Yes |
Yes |
Yes |
src_prepare | src-prepare p138 |
* |
Yes |
Yes |
Yes |
Yes |
src_prepare style | src-prepare p138 |
* |
no-op |
no-op |
no-op |
6 |
src_configure | src-configure p145 |
* |
Yes |
Yes |
Yes |
Yes |
src_compile style | src-compile p152 |
* |
2 |
2 |
2 |
2 |
Parallel tests | parallel-tests p167 |
No |
No |
No |
Yes |
Yes |
src_install style | src-install p170 |
no-op |
no-op |
4 |
4 |
6 |
pkg_info | pkg-info p182 |
Installed |
Installed |
Both |
Both |
Both |
default_ phase functions | default-phase-funcs p185 |
* |
pkg_nofetch, src_unpack, src_prepare, src_configure, src_compile, src_test |
pkg_nofetch, src_unpack, src_prepare, src_configure, src_compile, src_install, src_test |
pkg_nofetch, src_unpack, src_prepare, src_configure, src_compile, src_install, src_test |
pkg_nofetch, src_unpack, src_prepare, src_configure, src_compile, src_install, src_test |
AA | aa p201 |
Yes |
Yes |
No |
No |
No |
KV | kv p204 |
Yes |
Yes |
No |
No |
No |
EBUILD_PHASE_FUNC | ebuild-phase-func p204 |
No |
No |
No |
Yes |
Yes |
MERGE_TYPE | merge-type p204 |
No |
No |
Yes |
Yes |
Yes |
Sane locale settings | locale-settings p215 |
Undefined |
Undefined |
Undefined |
Undefined |
Yes |
Profile IUSE injection | profile-iuse-inject p218 |
No |
No |
No |
Yes |
Yes |
REPLACING_VERSIONS | replace-version-vars p219 |
No |
No |
Yes |
Yes |
Yes |
REPLACED_BY_VERSION | replace-version-vars p219 |
No |
No |
Yes |
Yes |
Yes |
EPREFIX, ED, EROOT | offset-prefix-vars p222 |
No |
Yes |
Yes |
Yes |
Yes |
failglob in global scope | failglob p226 |
No |
No |
No |
No |
Yes |
find is GNU? | gnu-find p226 |
Undefined |
Undefined |
Undefined |
Yes |
Yes |
Most utilities die | die-on-failure p230 |
No |
No |
Yes |
Yes |
Yes |
nonfatal | nonfatal p230 |
No |
No |
Yes |
Yes |
Yes |
dohard | banned-commands p233 |
Yes |
Yes |
Banned |
Banned |
Banned |
dosed | banned-commands p233 |
Yes |
Yes |
Banned |
Banned |
Banned |
einstall | banned-commands p233 |
Yes |
Yes |
Yes |
Yes |
Banned |
Option --host-root | host-root-option p236 |
No |
No |
No |
Yes |
Yes |
die -n | nonfatal-die p239 |
No |
No |
No |
No |
Yes |
eapply | eapply p243 |
No |
No |
No |
No |
Yes |
eapply_user | eapply-user p244 |
No |
No |
No |
No |
Yes |
econf arguments | econf-options p247 |
|
|
disable dependency tracking |
disable dependency tracking, disable silent rules |
disable dependency tracking, disable silent rules, docdir, htmldir |
dodoc -r | dodoc p250 |
No |
No |
Yes |
Yes |
Yes |
doheader | doheader p251 |
No |
No |
No |
Yes |
Yes |
doins handles symlinks | doins p252 |
No |
No |
Yes |
Yes |
Yes |
doman languages | doman-langs p253 |
* |
Yes |
Yes |
Yes |
Yes |
doman -i18n precedence | doman-langs p253 |
* |
No |
Yes |
Yes |
Yes |
new* support stdin | newfoo-stdin p253 |
No |
No |
No |
Yes |
Yes |
Controllable compression | docompress p269 |
No |
No |
Yes |
Yes |
Yes |
docompress | docompress p269 |
No |
No |
Yes |
Yes |
Yes |
use_with empty third arg | use-with p273 |
No |
No |
Yes |
Yes |
Yes |
usex | usex p273 |
No |
No |
No |
Yes |
Yes |
in_iuse | in-iuse p273 |
No |
No |
No |
No |
Yes |
unpack absolute paths | unpack-absolute p282 |
No |
No |
No |
No |
Yes |
unpack support for xz | unpack-extensions p283 |
No |
Yes |
Yes |
Yes |
Yes |
unpack support for txz | unpack-extensions p283 |
No |
No |
No |
No |
Yes |
unpack case-insensitive | unpack-ignore-case p283 |
No |
No |
No |
No |
Yes |
default function | default-func p284 |
* |
Yes |
Yes |
Yes |
Yes |
einstalldocs | einstalldocs p284 |
No |
No |
No |
No |
Yes |
get_libdir | get-libdir p285 |
No |
No |
No |
No |
Yes |
File mtimes preserved | mtime-preserve p293 |
Undefined |
Yes |
Yes |
Yes |
Yes |
Note: This chapter is informative and for convenience only. Refer to the main text for specifics.
EAPI 0 is the base EAPI.
EAPI 1 is EAPI 0 with the following changes:
EAPI 2 is EAPI 1 with the following changes:
EAPI 3 is EAPI 2 with the following changes:
EAPI 4 is EAPI 3 with the following changes:
EAPI 5 is EAPI 4 with the following changes:
EAPI 6 is EAPI 5 with the following changes:
1Another unofficial EAPI ‘kdebuild-1’ was a series of extensions to EAPI ‘1’ formerly used by the Gentoo KDE project. Some of its features have been included in EAPI ‘2’ or later.
2May change if a package has been updated (see 4.4.4).
3This variable is generally considered deprecated. However, ebuilds must still assume that the package manager sets it in the EAPIs supporting it. For example, a few configure scripts use this variable to find the aalib package; ebuilds calling such configure scripts must thus work around this.
4Not necessarily present when installing from a binary package. Ebuilds must not access the directory in global scope.
5Consistent and preserved across a single connected sequence of install or uninstall phases, but not between install and uninstall. When reinstalling a package, this variable must have different values for the install and the replacement.