Package Manager Specification

From fce6ff9819bdc1a8146ca276f43048a432915437 Mon Sep 17 00:00:00 2001 From: Ulrich Müller Date: Fri, 10 Apr 2015 16:49:24 +0200 Subject: Initial import. --- 4/pms.html | 9933 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 9933 insertions(+) create mode 100644 4/pms.html (limited to '4/pms.html') diff --git a/4/pms.html b/4/pms.html new file mode 100644 index 0000000..c89d793 --- /dev/null +++ b/4/pms.html @@ -0,0 +1,9933 @@ + + + + +Package Manager Specification + + + + + + + + +

+ + + +

Package Manager Specification

Stephen P. Bennett +
spb@exherbo.org
Ciaran McCreesh +
ciaran.mccreesh@googlemail.com

+
+

18th January 2011

+ + +

+1 Introduction +
1.1 Aims and Motivation +
1.2 Rationale +
1.3 Conventions +
2 EAPIs +
2.1 Definition +
2.2 Defined EAPIs +
2.3 Reserved EAPIs +
3 Names and Versions +
3.1 Restrictions upon Names +
  3.1.1 Category Names +
  3.1.2 Package Names +
  3.1.3 Slot Names +
  3.1.4 USE Flag Names +
  3.1.5 Repository Names +
  3.1.6 Keyword Names +
3.2 Version Specifications +
3.3 Version Comparison +
3.4 Uniqueness of versions +
4 Tree Layout +
4.1 Top Level +
4.2 Category Directories +
4.3 Package Directories +
4.4 The Profiles Directory +
  4.4.1 The profiles.desc file +
  4.4.2 The thirdpartymirrors file +
  4.4.3 use.desc and related files +
  4.4.4 The updates directory +
4.5 The Licenses Directory +
4.6 The Eclass Directory +
4.7 The Metadata Directory +
  4.7.1 The metadata cache + + +
5 Profiles +
5.1 General principles +
5.2 Files that make up a profile +
  5.2.1 The parent file +
  5.2.2 The eapi file +
  5.2.3 deprecated +
  5.2.4 make.defaults +
  5.2.5 virtuals +
  5.2.6 Simple line-based files +
  5.2.7 packages +
  5.2.8 packages.build +
  5.2.9 package.mask +
  5.2.10 package.provided +
  5.2.11 package.use +
  5.2.12 USE masking and forcing +
5.3 Profile variables +
  5.3.1 Incremental Variables +
  5.3.2 Specific variables and their meanings +
6 Old-Style Virtual Packages +
6.1 Dependencies on virtual packages +
7 Ebuild File Format +
8 Ebuild-defined Variables +
8.1 Metadata invariance +
8.2 Mandatory Ebuild-defined Variables +
8.3 Optional Ebuild-defined Variables +
  8.3.1 EAPI +
  8.3.2 RDEPEND value +
8.4 Magic Ebuild-defined Variables +
9 Dependencies +
9.1 Dependency Classes +
9.2 Dependency Specification Format +
  9.2.1 All-of Dependency Specifications +
  9.2.2 Use-conditional Dependency Specifications +
  9.2.3 Any-of Dependency Specifications +
  9.2.4 Exactly-one-of Dependency Specifications +
  9.2.5 Package Dependency Specifications +
  9.2.6 Use State Constraints +
  9.2.7 Restrict +
  9.2.8 Properties + + +
  9.2.9 SRC_URI +
10 Ebuild-defined Functions +
10.1 List of Functions +
  10.1.1 Initial Working Directories +
  10.1.2 pkg_pretend +
  10.1.3 pkg_setup +
  10.1.4 src_unpack +
  10.1.5 src_prepare +
  10.1.6 src_configure +
  10.1.7 src_compile +
  10.1.8 src_test +
  10.1.9 src_install +
  10.1.10 pkg_preinst +
  10.1.11 pkg_postinst +
  10.1.12 pkg_prerm +
  10.1.13 pkg_postrm +
  10.1.14 pkg_config +
  10.1.15 pkg_info +
  10.1.16 pkg_nofetch +
  10.1.17 default_ Phase Functions +
10.2 Call Order +
11 Eclasses +
11.1 The inherit command +
11.2 Eclass-defined Metadata Keys +
11.3 EXPORT_FUNCTIONS +
12 The Ebuild Environment +
12.1 Defined Variables +
  12.1.1 USE and IUSE Handling +
  12.1.2 REPLACING_VERSIONS and REPLACED_BY_VERSION +
  12.1.3 Offset-prefix variables EPREFIX, EROOT and ED +
12.2 The state of variables between functions +
12.3 Available commands +
  12.3.1 System commands +
  12.3.2 Commands provided by package dependencies +
  12.3.3 Ebuild-specific Commands +
12.4 The state of the system between functions +
13 Merging and Unmerging +
13.1 Overview +
13.2 Directories + + +
  13.2.1 Permissions +
  13.2.2 Empty Directories +
13.3 Regular Files +
  13.3.1 Permissions +
  13.3.2 File modification times +
  13.3.3 Configuration File Protection +
13.4 Symlinks +
  13.4.1 Rewriting +
13.5 Hard links +
13.6 Other Files +
14 Metadata Cache +
14.1 Directory Contents +
14.2 Cache File Format +
15 Glossary +
A metadata.xml +
B Unspecified Items +
C Historical Curiosities +
C.1 If-else use blocks +
C.2 cvs Versions +
C.3 use.defaults +
D Feature Availability by EAPI +
E Differences Between EAPIs +

+ + +

List of Algorithms

+1 Version comparison top-level logic +
2 Version comparison logic for numeric components +
3 Version comparison logic for each numeric component after the first +
4 Version comparison logic for letter components +
5 Version comparison logic for suffixes +
6 Version comparison logic for each suffix +
7 Version comparison logic for revision components +
8 USE masking logic +
9 econf --libdir logic +
10 Determining the library directory +

+ + +

Listings

+11.1 EXPORT_FUNCTIONS example: foo.eclass +
12.1 Environment state between functions +
12.2 einstall command +
C.1 If-else use blocks +

+ + +

List of Tables

8.1 EAPIs supporting IUSE defaults
8.2 EAPIs supporting various +ebuild-defined variables
8.3 EAPIs with RDEPEND=DEPEND Default
8.4 EAPIs +supporting DEFINED_PHASES
9.1 EAPIs supporting SRC_URI arrows
9.2 EAPIs +supporting SLOT dependencies
9.3 EAPIs supporting USE dependencies
9.4 Exclamation +mark strengths for EAPIs
10.1 EAPIs with S to WORKDIR fallbacks
10.2 EAPIs +supporting pkg_pretend
10.3 EAPIs supporting src_prepare
10.4 EAPIs supporting +src_configure
10.5 src_compile behaviour for EAPIs
10.6 src_install behaviour +for EAPIs
10.7 EAPIs supporting pkg_info on non-installed packages
10.8 EAPIs +supporting default_ phase functions
12.1 Defined variables
12.2 EAPIs supporting various +env variables
12.3 EAPIs supporting offset-prefix env variables
12.4 EAPIs supporting +offset-prefix
12.5 EAPI Command Failure Behaviour
12.6 Banned commands
12.7 Extra +econf arguments for EAPIs
12.8 EAPIs supporting dodoc -r
12.9 EAPIs supporting +symlinks for doins
12.10 doman language support options for EAPIs
12.11 EAPIs +supporting controllable compression
12.12 EAPI Behaviour for Use Queries not in +IUSE_EFFECTIVE
12.13 EAPIs supporting empty third argument in use_with and +use_enable
12.14 unpack extensions for EAPIs
12.15 EAPIs supporting the default +function
13.1 Preservation of file modification times (mtimes)
D.1 Features in EAPIs
+

+ + +

Acknowledgements

Thanks to Mike Kelly (package manager provided utilities, section 12.3.3), Danny van Dyk (ebuild +functions, section 10), David Leverton (various sections), Petteri Räty (environment state, +section 12.2) and Ulrich Müller (various sections) for contributions. Thanks to Christian +Faulhammer for fixing some of the more horrible formatting screwups and providing the EAPI +cheat sheet. Thanks also to Mike Frysinger and Brian Harring for proof-reading and suggestions for +fixes and/or clarification. +

Copyright and Licence

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/. +

Reporting Issues

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@gentoo.org mailing list. Patches will be reviewed by the PMS team, who will do one +of the following: +

Accept and apply the patch. +
Explain why the patch cannot be applied as-is. The patch may then be updated and + resubmitted if appropriate. +
Reject the patch outright. +
Take special action merited by the individual circumstances.

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. + + + + + + +

Chapter 1
Introduction

1.1 Aims and Motivation

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 15. +

This document does not specify any user or package manager configuration information. +

1.2 Rationale

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. +

1.3 Conventions

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. + + + + + + +

Chapter 2
EAPIs

2.1 Definition

An EAPI can be thought of as a ‘version’ of this specification to which a package conforms. An +EAPI value is a string, 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. +

2.2 Defined EAPIs

The following EAPIs are defined by this specification: +

+0: The ‘original’ base EAPI. +
+1: EAPI ‘1’ contains a number of extensions to EAPI ‘0’. Except where explicitly noted, it + is in all other ways identical to EAPI ‘0’. +
+2: EAPI ‘2’ contains a number of extensions to EAPI ‘1’. Except where explicitly noted, it + is in all other ways identical to EAPI ‘1’. +
+3: EAPI ‘3’ contains a number of extensions to EAPI ‘2’. Except where explicitly noted, it + is in all other ways identical to EAPI ‘2’. +
+4: EAPI ‘4’ contains a number of extensions to EAPI ‘3’. Except where explicitly noted, it + is in all other ways identical to EAPI ‘3’.

Except where explicitly noted, everything in this specification applies to all of the above +EAPIs.¹ +

2.3 Reserved EAPIs

+ + +

EAPIs whose value consists purely of an integer are reserved for future versions of this + specification. +
EAPIs whose value starts with the string paludis- are reserved for experimental use + by the Paludis package manager.

+ + + + + + +

Chapter 3
Names and Versions

3.1 Restrictions upon Names

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. +

3.1.1 Category Names

A category name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a +hyphen or a dot. +

Note: +A hyphen is not required because of the virtual category. Usually, however, category names will +contain a hyphen. +

3.1.2 Package Names

A package name may contain any of the characters [A-Za-z0-9+_-]. It must not begin with a +hyphen, and must not end in a hyphen followed by one or more digits. +

Note: +A package name does not include the category. The term qualified package name is used where a +category/package pair is meant. +

3.1.3 Slot Names

A slot name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a hyphen +or a dot. + + +

3.1.4 USE Flag Names

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 12.1.1. +

Note: +The at-sign is required for LINGUAS. +

3.1.5 Repository Names

A repository name may contain any of the characters [A-Za-z0-9_-]. It must not begin with a +hyphen. +

3.1.6 Keyword Names

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, to indicate that a package will only work +on listed targets. +

A tilde prefixed keyword is, by convention, used to indicate a less stable package. It is generally +assumed that any user accepting keyword ~foo will also accept foo. +

The exact meaning of any keywords value is beyond the scope of this specification. +

3.2 Version Specifications

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 suffixed by an optional integer. +

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. + + +

3.3 Version Comparison

Version specifications are compared component by component, moving from left to right, as +detailed in Algorithm 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. +

+ + +

Algorithm 1: Version comparison top-level logic

+ + 1: let A and B be the versions to be compared +
2: compare numeric components using Algorithm 2 +
3: compare letter components using Algorithm 4 +
4: compare suffixes using Algorithm 5 +
5: compare revision components using Algorithm 7 +
6: return A = B +

+ + +

Algorithm 2: Version comparison logic for numeric components

+ + 1: define the notations An_k and Bn_k to mean the k^th numeric component of A and B + respectively, using 0-based indexing +
2: if An₀ > Bn₀ using integer comparison then + +
3: return A > B + +
4: else if An₀ < Bn₀ using integer comparison then + +
5: return A < B + +
6: end if +
7: let Ann be the number of numeric components of A +
8: let Bnn be the number of numeric components of B +
9: for all i such that i ≥ 1 and i < Ann and i < Bnn, in ascending order do + +
10: compare An_i and Bn_i using Algorithm 3 + +
11: end for +
12: if Ann > Bnn then + +
13: return A > B + +
14: else if Ann < Bnn then + +
15: return A < B + +
16: end if +

+ + +

Algorithm 3: Version comparison logic for each numeric component after the first

+ + 1: if either An_i or Bn_i has a leading 0 then + +
2: let An′_i be An_i with any trailing 0s removed +
3: let Bn′_i be Bn_i with any trailing 0s removed +
4: if An′_i > Bn′_i using ASCII stringwise comparison then + +
5: return A > B + +
6: else if An′_i < Bn′_i using ASCII stringwise comparison then + +
7: return A < B + +
8: end if + +
9: else + +
10: if An_i > Bn_i using integer comparison then + +
11: return A > B + +
12: else if An_i < Bn_i using integer comparison then + +
13: return A < B + +
14: end if + +
15: end if +

+ + +

Algorithm 4: Version comparison logic for letter components

+ + 1: let Al be the letter component of A if any, otherwise the empty string +
2: let Bl be the letter component of B if any, otherwise the empty string +
3: if Al > Bl using ASCII stringwise comparison then + +
4: return A > B + +
5: else if Al < Bl using ASCII stringwise comparison then + +
6: return A < B + +
7: end if +

+ + +

Algorithm 5: Version comparison logic for suffixes

+ + 1: define the notations As_k and Bs_k to mean the k^th suffix of A and B respectively, using + 0-based indexing +
2: let Asn be the number of suffixes of A +
3: let Bsn be the number of suffixes of B +
4: for all i such that i ≥ 0 and i < Asn and i < Bsn, in ascending order do + +
5: compare As_i and Bs_i using Algorithm 6 + +
6: end for +
7: if Asn > Bsn then + +
8: if As_Bsn is of type _p then + +
9: return A > B + +
10: else + +
11: return A < B + +
12: end if + +
13: else if Asn < Bsn then + +
14: if Bs_Asn is of type _p then + +
15: return A < B + +
16: else + +
17: return A > B + +
18: end if + +
19: end if +

+ + +

Algorithm 6: Version comparison logic for each suffix

+ + 1: if As_i and Bs_i are of the same type (_alpha vs _beta etc) then + +
2: let As′_i be the integer part of As_i if any, otherwise 0 +
3: let Bs′_i be the integer part of Bs_i if any, otherwise 0 +
4: if As′_i > Bs′_i, using integer comparison then + +
5: return A > B + +
6: else if As′_i < Bs′_i, using integer comparison then + +
7: return A < B + +
8: end if + +
9: else if the type of As_i is greater than the type of Bs_i using the ordering + _alpha < _beta < _pre < _rc < _p then + +
10: return A > B + +
11: else + +
12: return A < B + +
13: end if +

+ + +

Algorithm 7: Version comparison logic for revision components

+ + 1: let Ar be the integer part of the revision component of A if any, otherwise 0 +
2: let Br be the integer part of the revision component of B if any, otherwise 0 +
3: if Ar > Br using integer comparison then + +
4: return A > B + +
5: else if Ar < Br using integer comparison then + +
6: return A < B + +
7: end if +

+ + +

3.4 Uniqueness of versions

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. + + + + + + +

Chapter 4
Tree Layout

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. +

4.1 Top Level

An ebuild repository shall occupy one directory on disk, with the following subdirectories: +

One directory per category, whose name shall be the name of the category. The layout + of these directories shall be as described in section 4.2. +
A profiles directory, described in section 4.4. +
A licenses directory (optional), described in section 4.5. +
An eclass directory (optional), described in section 4.6. +
A metadata directory (optional), described in section 4.7. +
Other optional support files and directories (skeleton ebuilds or ChangeLogs, for + example) may exist but are not covered by this specification. The package manager + must ignore any of these files or directories that it does not recognise. +

4.2 Category Directories

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: +

A metadata.xml file, as described in appendix A. Optional. +
Zero or more package directories, one for each package in the category, as described + in section 4.3. The name of the package directory shall be the corresponding package + name.

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). + + +

4.3 Package Directories

A package directory contains the following: +

Zero or more ebuilds. These are as described in section 7 and others. +
A metadata.xml file, as described in appendix A. Optional only for legacy support. +
A ChangeLog, in a format determined by the provider of the repository. Optional. +
A Manifest file, whose format is described in [1]. +
A files directory, containing any support files needed by the ebuilds. Optional.

Any ebuild in a package directory must be named name-ver.suffix, where: +

name is the (unqualified) package name. +
ver is the package’s version. +
suffix is ebuild.

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. +

4.4 The Profiles Directory

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 profile +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. + + +

+arch.list: Contains a list, one entry per line, of permissible values for the ARCH variable, + and hence permissible keywords for packages in this repository. +
+categories: Contains a list, one entry per line, of categories provided by this repository. +
+eapi: See above. +
+info_pkgs: Contains a list, one entry per line, of qualified package names. Any package + matching one of these is to be listed when a package manager displays a ‘system + information’ listing. +
+info_vars: Contains a list, one entry per line, of profile, configuration, and environment + variables which are considered to be of interest. The value of each of these variables + may be shown when the package manager displays a ‘system information’ listing. +
+package.mask: Contains a list, one entry per line, of package dependency specifications + (using the directory’s EAPI). Any package version matching one of these is considered + to be masked, and will not be installed regardless of profile unless it is unmasked by + the user configuration. +
+profiles.desc: Described below in section 4.4.1. +
+repo_name: Contains, on a single line, the name of this repository. The repository name + must conform to section 3.1.5. +
+thirdpartymirrors: Described below in section 4.4.2. +
+use.desc: Contains descriptions of valid global USE flags for this repository. The format is + described in section 4.4.3. +
+use.local.desc: Contains descriptions of valid local USE flags for this repository, along with + the packages to which they apply. The format is as described in section 4.4.3. +
+desc/: This directory contains files analogous to use.desc for the various USE_EXPAND + variables. Each file in it is named <varname>.desc, where <varname> is the variable + name, in lowercase, whose possible values the file describes. The format of each file is + as for use.desc, described in section 4.4.3. The USE_EXPAND name is not included as + a prefix here. +
+updates/: This directory is described in section 4.4.4.

4.4.1 The profiles.desc file

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: + + +

+<keyword> <profile path> <stability>

Where: +

<keyword> is the default keyword for the profile and the ARCH for which the profile is + valid. +
<profile path> is the (relative) path from the profiles directory to the profile in + question. +
<stability> indicates the stability of the profile. This may be useful for QA tools, + which may wish to display warnings with a reduced severity for some profiles. The + values stable and dev are widely used, but repositories may use other values.

Fields are whitespace-delimited. +

4.4.2 The thirdpartymirrors file

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: + + +

+<mirror name> <mirror 1> <mirror 2> ... <mirror n>

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. +

4.4.3 use.desc and related files

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: + + +

+<flagname> - <description>

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: + + +

+<category/package>:<flagname> - <description>

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. +

4.4.4 The updates directory

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: + + +

+move <qpn1> <qpn2> +
slotmove <spec> <slot1> <slot2>

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. +

4.5 The Licenses Directory

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 8.2, and will contain the complete text of the license in human-readable form. Plain text +format is strongly preferred but not required. +

4.6 The Eclass Directory

The eclass directory shall contain copies of the eclasses provided by this repository. The format of +these files is described in section 11. It may also contain, in their own directory, support files +needed by these eclasses. +

4.7 The Metadata Directory

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. + + +

4.7.1 The metadata cache

The metadata/cache directory may contain a cached form of all important ebuild metadata +variables. The contents of this directory are described in section 14. + + + + + + +

Chapter 5
Profiles

5.1 General principles

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. +

5.2 Files that make up a profile

5.2.1 The parent file

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. +

5.2.2 The eapi file

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 not inherited via +the parent file. + + +

5.2.3 deprecated

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. +

5.2.4 make.defaults

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: +

Variables to the right of the equals sign in the form ${foo} or $foo are recognised and + expanded from variables previously set in this or earlier make.defaults files. +
One logical line may be continued over multiple physical lines by escaping the newline + with a backslash. A quoted string may be continued over multiple physical lines by + either a simple newline or a backslash-escaped newline. +
Backslashes, except for line continuations, are not allowed.

5.2.5 virtuals

The virtuals file defines default providers for “old-style” virtual packages. It is a simple line-based +file, with each line containing two whitespace-delimited tokens. The first is a virtual package name +(for example, virtual/alsa) and the second is a qualified package name. Blank lines and those +beginning with a # character are ignored. When attempting to resolve a virtual name to a concrete +package, the specification defined in the active profile’s virtuals list should be used if no provider +is already installed. +

The virtuals file is inherited in the simplest manner: all entries from the parent profile are +loaded, then entries from the current profile. If a virtual package name appears in both, the entry +in the parent profile is discarded. + + +

5.2.6 Simple line-based files

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. +

5.2.7 packages

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 the atom 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. +

5.2.8 packages.build

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. +

5.2.9 package.mask

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. + + +

5.2.10 package.provided

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. +

5.2.11 package.use

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. +

5.2.12 USE masking and forcing

This section covers the four files use.mask, use.force, package.use.mask and +package.use.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. The precise manner +in which they 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 8. +

+ + +

Algorithm 8: USE masking logic

+ + 1: let masked = false +
2: for each profile in the inheritance tree, depth first do + +
3: if use.mask contains flag then + +
4: let masked = true + +
5: else if use.mask contains -flag then + +
6: let masked = false + +
7: end if +
8: for each line in package.use.mask, in order, for which the spec matches package do + +
9: if line contains flag then + +
10: let masked = true + +
11: else if line contains -flag then + +
12: let masked = false + +
13: end if + +
14: end for + +
15: end for +

+ + +

The logic for use.force and package.use.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. +

5.3 Profile variables

This section documents variables that have special meaning, or special behaviour, when defined in +a profile’s make.defaults file. +

5.3.1 Incremental Variables

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: +

USE +
USE_EXPAND +
USE_EXPAND_HIDDEN +
CONFIG_PROTECT +
CONFIG_PROTECT_MASK

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. +

5.3.2 Specific variables and their meanings

The following variables have specific meanings when set in profiles. +

+ARCH: The system’s architecture. Must be a value listed in profiles/arch.list; see + section 4.4 for more information. Must be equal to the primary KEYWORD for this profile. + + +
+CONFIG_PROTECT, CONFIG_PROTECT_MASK: Contain + whitespace-delimited lists used to control the configuration file protection. Described + more fully in chapter 13.3.3. +
+USE: Defines the list of default USE flags for this profile. Flags may be added or removed + by the user’s configuration. USE_EXPAND values must not be specified in this way. +
+USE_EXPAND: Defines a list of variables which are to be treated incrementally and + whose contents are to be expanded into the USE variable as passed to ebuilds. See + section 12.1.1 for details. +
+USE_EXPAND_HIDDEN: Contains a (possibly empty) subset of names from + USE_EXPAND. The package manager may use this set as a hint to avoid displaying + uninteresting or unhelpful information to an end user.

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. + + + + + + +

Chapter 6
Old-Style Virtual Packages

Old-style virtuals are pseudo-packages—they can be depended upon or installed, but do not exist +in the ebuild repository. An old-style virtual requires several things in the repository: at least one +ebuild must list the virtual in its PROVIDE variable, and there must be at least one entry in a +profiles virtuals file listing the default provider for each profile—see sections 8.3 and 5.2.5 for +specifics on these two. Old-style virtuals require special handling as regards dependencies; this is +described below. +

All old-style virtuals must use the category virtual. Not all packages using the virtual category +may be assumed to be old style virtuals. +

Note: +A new-style virtual is simply an ebuild which install no files and use its dependency strings to +select providers. By convention, and to ease migration, these are also placed in the virtual +category. +

6.1 Dependencies on virtual packages

When a dependency on a virtual package is encountered, it must be resolved into a real package +before it can be satisfied. There are two factors that affect this process: whether a package +providing the virtual is installed, and the virtuals file in the active profile (section 5.2.5). If a +package is already installed which satisfies the virtual requirement (via PROVIDE), then it should be +used to satisfy the dependency. Otherwise, the profiles virtuals file (section 5.2.5) should be +consulted to choose an appropriate provider. +

Dependencies on old style virtuals must not use any kind of version restriction. +

Blocks on provided virtuals have special behaviour documented in section 9.2.5.2. + + + + + + +

Chapter 7
Ebuild File Format

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 3.2 or later, see footnote 6 on page 170. The file encoding must +be UTF-8 with Unix-style newlines. When sourced, the ebuild must define certain variables and +functions (see sections 8 and 10 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. + + + + + + +

Chapter 8
Ebuild-defined Variables

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 12.1. +

8.1 Metadata invariance

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. +

8.2 Mandatory Ebuild-defined Variables

All ebuilds must define at least the following variables: +

+DESCRIPTION

A short human-readable description of the package’s purpose. May be + defined by an eclass. Must not be empty. +

+HOMEPAGE

The URI or URIs for a package’s homepage, including protocols. May be + defined by an eclass. See section 9 for full syntax. +

+IUSE

The USE flags used by the ebuild. Any eclass that works with USE flags must also set + IUSE, listing only the variables used by that eclass. The package manager is responsible + for merging these values. See section 12.1.1 for discussion on which values must be + listed this variable. +

+ IUSE-DEFAULTS

In EAPIs shown in table 8.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. +

+KEYWORDS

A whitespace separated list of keywords for the ebuild. Each token must be + a valid keyword name, as per section 3.1.6. May include -*, which indicates that the + package will only work on explicitly listed archs. May include -arch, which indicates + that the package will not work on the specified arch. May be empty, which indicates + uncertain functionality on any architecture. May be defined in an eclass. + + +

+LICENSE

The package’s license. Each text token must correspond to a tree “licenses/” + entry (see section 4.5). See section 9 for full syntax. May be defined by an eclass. +

+SLOT

The package’s slot. Must be a valid slot name, as per section 3.1.3. May be defined + by an eclass. Must not be empty. +

+SRC_URI

A list of source URIs for the package. Valid protocols are http://, https://, + ftp:// and mirror:// (see section 4.4.2 for mirror behaviour). Fetch restricted + packages may include URL parts consisting of just a filename. May be defined by an + eclass. See section 9 for full syntax.

If any of these variables are undefined, or 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. +

+ + +

Table 8.1: EAPIs supporting IUSE defaults

+ + + + +

EAPI	Supports IUSE defaults? +
0	No
1	Yes
2	Yes
3	Yes
4	Yes

+ + +

8.3 Optional Ebuild-defined Variables

Ebuilds may define any of the following variables: +

+DEPEND

See section 9. +

+EAPI

The EAPI. See below for defaults. +

+PDEPEND

See section 9. +

+PROVIDE

Zero or more qualified package names of any old style virtuals provided by this + package. See section 9 for full syntax. +

+RDEPEND

See section 9. For some EAPIs, RDEPEND has special behaviour for its value if + unset and when used with an eclass. See section 8.3.2 for details. +

+RESTRICT

Zero or more behaviour restrictions for this package. See section 9.2.7 for + value meanings and section 9 for full syntax. +

+PROPERTIES

+ PROPERTIES Zero or more properties for this package. See section 9.2.8 for value + meanings and section 9 for full syntax. For EAPIs listed in table 8.2 as having optional + support, ebuilds must not rely upon the package manager recognising or understanding + this variable in any way. +

+REQUIRED_USE

+ REQUIRED-USE Zero or more assertions that must be met by the configuration of + USE flags to be valid for this ebuild. See section 9.2.6 for description and section 9 for + full syntax. Only in EAPIs listed in table 8.2 as supporting REQUIRED_USE.

+ + +

Table 8.2: EAPIs supporting various ebuild-defined variables

+ + + + + +

EAPI	Supports PROPERTIES? +
Supports REQUIRED_USE? +
0	Optionally	No
1	Optionally	No
2	Optionally	No
3	Optionally	No
4	Yes	Yes

+ + +

8.3.1 EAPI

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. +

8.3.2 RDEPEND value

+ RDEPEND-DEPEND

In EAPIs listed in table 8.3 as having RDEPEND=DEPEND, if RDEPEND is unset (but not if it is set to +an empty string) in an ebuild, the package manager must set its value to be 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 added to +RDEPEND. +

+ + +

Table 8.3: EAPIs with RDEPEND=DEPEND Default

+ + + + +

EAPI	RDEPEND=DEPEND? +
0	Yes
1	Yes
2	Yes
3	Yes
4	No

+ + +

8.4 Magic Ebuild-defined Variables

The following variables must be defined by inherit (see section 11.1, and may be considered to be +part of the ebuild’s metadata: +

+ECLASS: The current eclass, or unset if there is no current eclass. This is handled magically + by inherit and must not be modified manually. +
+INHERITED: List of inherited eclass names. Again, this is handled magically by inherit.

Note: +Thus, by extension of section 8.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: +

+DEFINED_PHASES

+ DEFINED-PHASES A space separated arbitrarily ordered list of phase names + (e. g. configure setup unpack) whose phase functions are defined by the ebuild or + an eclass inherited by the ebuild. If no phase functions are defined, a single hyphen + is used instead of an empty string. For EAPIs listed in table 8.4 as having optional + DEFINED_PHASES support, package managers may not rely upon the metadata cache + having this variable defined, and must treat an empty string as “this information is not + available”.

Note: +Thus, by extension of section 8.1, phase functions must not be defined based upon any variant +condition. +

+ + +

Table 8.4: EAPIs supporting DEFINED_PHASES

+ + + + + +

EAPI	Supports DEFINED_PHASES? +
0	Optionally
1	Optionally
2	Optionally
3	Optionally
4	Yes

+ + +

+ + + + + + +

Chapter 9
Dependencies

9.1 Dependency Classes

There are three classes of dependencies supported by ebuilds: +

Build dependencies (DEPEND). These must be installed and usable before the ebuild is + installed. +
Runtime dependencies (RDEPEND). These must be installed and usable before the ebuild + is treated as usable. +
Post dependencies (PDEPEND). These must be installed at some point.

In addition, SRC_URI, HOMEPAGE, PROVIDE, RESTRICT, PROPERTIES, LICENSE and REQUIRED_USE use +dependency-style specifications to specify their values. +

9.2 Dependency Specification Format

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. +

A package dependency specification. Permitted in DEPEND, RDEPEND, PDEPEND. +
A simple qualified package name. Permitted in PROVIDE (and inside DEPEND etc via the + previous item). +
A URI, in the form proto://host/path. Permitted in SRC_URI and HOMEPAGE. In + EAPIs listed in table 9.1 as supporting SRC_URI arrows, may optionally be followed + by whitespace, then ->, then whitespace, then a simple filename when in SRC_URI. For + SRC_URI behaviour, see section 9.2.9. +
A flat filename. Permitted in SRC_URI. +
A license name (e. g. GPL-2). Permitted in LICENSE. +
A use flag name, optionally preceded by an exclamation mark. Permitted in + REQUIRED_USE. +
A simple string. Permitted in RESTRICT and PROPERTIES. +
An all-of group, which consists of an open parenthesis, followed by whitespace, + followed by zero or more of (a dependency item of any kind followed by whitespace), + followed by a close parenthesis. More formally: all-of ::= ’(’ whitespace (item + whitespace)* ’)’. Permitted in all specification style variables. +
An any-of group, which consists of the string ||, followed by whitespace, followed + by an open parenthesis, followed by whitespace, followed by zero or more of + + + (a dependency item of any kind followed by whitespace), followed by a close + parenthesis. More formally: any-of ::= ’||’ whitespace ’(’ whitespace (item + whitespace)* ’)’. Permitted in DEPEND, RDEPEND, PDEPEND, LICENSE, REQUIRED_USE. +
An exactly-one-of group, which consists of the string ^^, followed by whitespace, + followed by an open parenthesis, followed by whitespace, followed by zero or + more of (a dependency item of any kind followed by whitespace), followed by + a close parenthesis. More formally: exactly-one-of ::= ’^^’ whitespace ’(’ + whitespace (item whitespace)* ’)’. Permitted in REQUIRED_USE. +
A use-conditional group, which consists of an optional exclamation mark, + followed by a use flag name, followed by a question mark, followed by + whitespace, followed by an open parenthesis, followed by whitespace, followed + by zero or more of (a dependency item of any kind followed by whitespace), + followed by a close parenthesis. More formally: use-conditional ::= ’!’? + flag-name ’?’ whitespace ’(’ whitespace (item whitespace)* ’)’. Permitted + in all specification style variables.

In particular, note that whitespace is not optional. +

+ + +

Table 9.1: EAPIs supporting SRC_URI arrows

+ + + + +

EAPI	Supports SRC_URI arrows? +
0	No
1	No
2	Yes
3	Yes
4	Yes

+ + +

9.2.1 All-of Dependency Specifications

In an all-of group, all of the child elements must be matched. +

9.2.2 Use-conditional Dependency Specifications

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 12.1.1. +

9.2.3 Any-of Dependency Specifications

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. +

9.2.4 Exactly-one-of Dependency Specifications

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. +

9.2.5 Package Dependency Specifications

A package dependency can be in one of the following base formats. A package manager must warn +or error on non-compliant input. + + +

A simple category/package name. +
An operator, as described + in section 9.2.5.1, followed immediately by category/package, followed by a hyphen, + followed by a version specification.

In EAPIs shown in table 9.2 as supporting SLOT dependencies, either of the above formats may +additionally be suffixed by a :slot restriction, as described in section 9.2.5.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 9.3 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 9.2.5.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. +

+ + +

Table 9.2: EAPIs supporting SLOT dependencies

+ + + + +

EAPI	Supports SLOT dependencies? +
0	No
1	Yes
2	Yes
3	Yes
4	Yes

+ + +

Table 9.3: EAPIs supporting USE dependencies

+ + + + + +

EAPI	Supports USE dependencies? +
0	No
1	No
2	2-style
3	2-style
4	4-style

+ + +

9.2.5.1 Operators

The following operators are available: +

+<: Strictly less than the specified version. +
+<=: Less than or equal to the specified version. +
+=: Exactly equal to the specified version. Special exception: if the version specified has an + asterisk immediately following it, a string prefix comparison is used instead. When an + asterisk is used, the specification must remain valid if the asterisk were removed. (An + asterisk used with any other operator is illegal.) +
+~: Equal to the specified version, except the revision part of the matching package may be + greater than the revision part of the specified version (-r0 is assumed if no revision is + explicitly stated). +
+>=: Greater than or equal to the specified version. +
+>: Strictly greater than the specified version.

9.2.5.2 Block Operator

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: +

Blocks on a package provided exclusively by the ebuild do not count. +
Blocks on the ebuild itself do not count.

+ 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 9.4. +

+ + +

Table 9.4: Exclamation mark strengths for EAPIs

+ + + + + + +

EAPI	!	!! +
0	Unspecified	Forbidden
1	Unspecified	Forbidden
2	Weak	Strong
3	Weak	Strong
4	Weak	Strong

+ + +

9.2.5.3 Slot Dependencies

+ 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. +

9.2.5.4 2-Style and 4-Style Use Dependencies

A 2-style or 4-style use dependency consists of one of the following: +

+[opt]: The flag must be enabled. +
+[opt=]: The flag must be enabled if the flag is enabled for the package with the dependency, + or disabled otherwise. +
+[!opt=]: The flag must be disabled if the flag is enabled for the package with the dependency, + or enabled otherwise. +
+[opt?]: The flag must be enabled if the flag is enabled for the package with the dependency. +
+[!opt?]: The flag must be disabled if the use flag is disabled for the package with the + dependency. +
+[-opt]: The flag must be disabled.

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. +

9.2.6 Use State Constraints

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. +

9.2.7 Restrict

The following tokens are permitted inside RESTRICT: +

+mirror: The package’s SRC_URI entries may not be mirrored, and mirrors should not be + checked when fetching. +
+fetch: The package’s SRC_URI entries may not be downloaded automatically. If entries are + not available, pkg_nofetch is called. +
+strip: No stripping of debug symbols from files to be installed may be performed. +
+userpriv: The package manager may not drop root privileges when building the package. +
+test: The src_test phase must not be run. +
+sandbox: The sandbox tool must not be used when building the package.

Package managers may recognise other tokens, but ebuilds may not rely upon them being +supported. +

9.2.8 Properties

The following tokens are permitted inside PROPERTIES: + + +

+interactive: The package may require interaction with the user via the tty.

Ebuilds may not rely upon any token being supported. +

9.2.9 SRC_URI

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 9.2.7 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. + + + + + + +

Chapter 10
Ebuild-defined Functions

10.1 List of Functions

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 12.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. +

10.1.1 Initial Working Directories

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 10.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: +

The A variable contains no items. +
The phase function in question is not in DEFINED_PHASES. +
None of the phase functions unpack, prepare, configure, compile or install, if + supported by the EAPI in question and occurring prior to the phase about to be + executed, are in DEFINED_PHASES.

+ + +

Table 10.1: EAPIs with S to WORKDIR fallbacks

+ + + + + +

EAPI	Fallback to WORKDIR permitted? +
0	Always
1	Always
2	Always
3	Always
4	Conditional error

+ + +

10.1.2 pkg_pretend

+ PKG-PRETEND

The pkg_pretend function is only called for EAPIs listed in table 10.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. +

+ + +

Table 10.2: EAPIs supporting pkg_pretend

+ + + + +

EAPI	Supports pkg_pretend? +
0	No
1	No
2	No
3	No
4	Yes

+ + +

10.1.3 pkg_setup

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. +

10.1.4 src_unpack

+ SRC-UNPACK

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_unpack() { +
    if [[ -n ${A} ]]; then +
        unpack ${A} +
    fi +
}

10.1.5 src_prepare

+ SRC-PREPARE

The src_prepare function is only called for EAPIs listed in table 10.3 as supporting +it. +

The src_prepare function can be used for post-unpack source preparation. The default +implementation does nothing. +

The initial working directory is S, with an error or fallback to WORKDIR as discussed in +section 10.1.1. +

+ + +

Table 10.3: EAPIs supporting src_prepare

+ + + + +

EAPI	Supports src_prepare? +
0	No
1	No
2	Yes
3	Yes
4	Yes

+ + +

10.1.6 src_configure

+ SRC-CONFIGURE

The src_configure function is only called for EAPIs listed in table 10.4 as supporting +it. +

The initial working directory is S, with an error or fallback to WORKDIR as discussed in +section 10.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_configure() { +
    if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then +
        econf +
    fi +
}

+ + +

Table 10.4: EAPIs supporting src_configure

+ + + + +

EAPI	Supports src_configure? +
0	No
1	No
2	Yes
3	Yes
4	Yes

+ + +

10.1.7 src_compile

+ 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 10.1.1. +

+ SRC-COMPILE-0

For EAPIs listed in table 10.5 as using format 0, the default implementation used when the ebuild +lacks the src_compile function shall behave as: + + +

+src_compile() { +
    if [[ -x ./configure ]]; then +
        econf +
    fi +
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then +
        emake || die "emake failed" +
    fi +
}

+ SRC-COMPILE-1

For EAPIs listed in table 10.5 as using format 1, the default implementation used when the ebuild +lacks the src_compile function shall behave as: + + +

+src_compile() { +
    if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then +
        econf +
    fi +
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then +
        emake || die "emake failed" +
    fi +
}

+ SRC-COMPILE-2

For EAPIs listed in table 10.5 as using format 2, the default implementation used when the ebuild +lacks the src_compile function shall behave as: + + +

+src_compile() { +
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then +
        emake || die "emake failed" +
    fi +
}

+ + +

Table 10.5: src_compile behaviour for EAPIs

+ + + + +

EAPI	Format +
0	0
1	1
2	2
3	2
4	2

+ + +

10.1.8 src_test

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 make check if and only if such a target is available, or if not run make test, if and +only such a target is available. In both cases, if make returns non-zero the build must be +aborted. +

The src_test function may be disabled by RESTRICT. See section 9.2.7. +

10.1.9 src_install

+ 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 10.1.1. +

+ SRC-INSTALL-4

For EAPIs listed in table 10.6 as using format 4, the default implementation used when the ebuild +lacks the src_install function shall behave as: + + +

+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 +
}

For other EAPIs, the default implementation used when the ebuild lacks the src_install function +is a no-op. +

+ + +

Table 10.6: src_install behaviour for EAPIs

+ + + + + +

EAPI	Format +
0	no-op
1	no-op
2	no-op
3	no-op
4	4

+ + +

10.1.10 pkg_preinst

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. +

10.1.11 pkg_postinst

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. +

10.1.12 pkg_prerm

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. +

10.1.13 pkg_postrm

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. + + +

10.1.14 pkg_config

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. +

10.1.15 pkg_info

+ 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 10.7 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. +

+ + +

Table 10.7: EAPIs supporting pkg_info on non-installed packages

+ + + + +

EAPI	Supports pkg_info on non-installed packages? +
0	No
1	No
2	No
3	No
4	Yes

+ + +

10.1.16 pkg_nofetch

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. +

10.1.17 default_ Phase Functions

+ DEFAULT-PHASE-FUNCS

In EAPIs listed in table 10.8 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. +

+ + +

Table 10.8: EAPIs supporting default_ phase functions

+ + + + + +

EAPI	Supports default_ functions in phases +
0	None
1	None
2	pkg_nofetch, src_unpack, src_prepare, +src_configure, src_compile, src_test
3	pkg_nofetch, src_unpack, src_prepare, +src_configure, src_compile, src_test
4	pkg_nofetch, src_unpack, src_prepare, +src_configure, src_compile, src_install, +src_test

+ + +

10.2 Call Order

The call order for installing a package is: +

pkg_pretend (only for EAPIs listed in table 10.2), which is called outside of the normal + call order process. +
pkg_setup +
src_unpack +
src_prepare (only for EAPIs listed in table 10.3) +
src_configure (only for EAPIs listed in table 10.4) +
src_compile +
src_test (except if RESTRICT=test) +
src_install +
pkg_preinst +
pkg_postinst

The call order for uninstalling a package is: +

pkg_prerm +
pkg_postrm

The call order for upgrading, downgrading or reinstalling a package is: +

pkg_pretend (only for EAPIs listed in table 10.2), which is called outside of the normal + call order process. +
pkg_setup +
src_unpack +
src_prepare (only for EAPIs listed in table 10.3) +
src_configure (only for EAPIs listed in table 10.4) +
src_compile +
src_test (except if RESTRICT=test) + + +
src_install +
pkg_preinst +
pkg_prerm for the package being replaced +
pkg_postrm for the package being replaced +
pkg_postinst

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. + + + + + + +

Chapter 11
Eclasses

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. +

11.1 The inherit command

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 ECLASS variable is set to the name of the current eclass, when sourcing that eclass. +
Once all inheriting has been done, the INHERITED metadata variable contains the name + of every eclass used, separated by whitespace.

11.2 Eclass-defined Metadata Keys

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 8.3.2 are applied. +

11.3 EXPORT_FUNCTIONS

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 11.1 and is a snippet from a hypothetical foo.eclass. + + +

+ + +

Listing 11.1: EXPORT_FUNCTIONS example: foo.eclass

+ + +

+foo_src_compile() +
{ +
    econf --enable-gerbil \ +
            $(use_enable fnord) +
    emake gerbil || die "Couldn’t make a gerbil" +
    emake || die "emake failed" +
} +
+
EXPORT_FUNCTIONS src_compile +

+ + +

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. + + + + + + +

Chapter 12
The Ebuild Environment

12.1 Defined Variables

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 12.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 12.1: Defined variables +
+
Variable	Legal in	Consistent?	Description +
+

			+
P	+ all	No¹	+ Package name and version, without the +revision part. For example, vim-7.0.174.
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.
PF	+ all	Yes	+ Package name, version, and revision (if any), +for example vim-7.0.174-r1.
A	+ src_*	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.
AA²	+ src_*	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 12.2 +as supporting AA.
FILESDIR	+ src_*³	No	+ The full path to the package’s files directory, +used for small support files or patches. 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.
PORTDIR	+ ditto	No	+ The full path to the master repository’s base +directory.
DISTDIR	+ ditto	No	+ The full path to the directory in which the files +in the A variable are stored.
ECLASSDIR	+ ditto	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	+ Like ROOT, but with EPREFIX appended. This +is a convenience variable. See also the EPREFIX +variable.
T	+ All	Partially⁴	+ 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 12.1.3.
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	+ Like D, but with EPREFIX appended. This is +a convenience variable. See also the EPREFIX +variable.
IMAGE⁵	+ pkg_preinst, +pkg_postinst	Yes	+ Equal to D.
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 12.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.
WORKDIR	+ src_*, +global scope	Yes	+ The full path to the ebuild’s working directory, +in which 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 12.2 for global variables apply.
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 12.2 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 12.2 as +supporting MERGE_TYPE.
REPLACING_VERSIONS	+ pkg_* (see +text)	Yes	+ A whitespace-separated list of versions of this +package (including revision, if specified) that +are being replaced (uninstalled or overwritten) +as a result of this install. See section 12.1.2. +Only for EAPIs listed in table 12.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 12.1.2. +Only for EAPIs listed in table 12.2 as +supporting REPLACED_BY_VERSION.

+ + + +

+ + +

Table 12.2: EAPIs supporting various env variables

+ + + + +

EAPI	AA?	KV?	MERGE_TYPE?	REPLACING_VERSIONS?	REPLACED_BY_VERSION? +
0	Yes	Yes	No	No	No
1	Yes	Yes	No	No	No
2	Yes	Yes	No	No	No
3	Yes	Yes	No	No	No
4	No	No	Yes	Yes	Yes

+ + +

Table 12.3: EAPIs supporting offset-prefix env variables

+ + + + +

EAPI	EPREFIX?	EROOT?	ED? +
0	No	No	No
1	No	No	No
2	No	No	No
3	Yes	Yes	Yes
4	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. +

12.1.1 USE and IUSE Handling

This section discusses the handling of four variables: +

+IUSE: is the variable calculated from the IUSE values defined in ebuilds and eclasses. +
+IUSE_REFERENCEABLE: is a variable calculated from IUSE and a variety of other + sources described below. It is purely a conceptual variable; it is not exported to the + ebuild environment. Values in IUSE_REFERENCEABLE may legally be used in queries + from other packages about an ebuild’s state (for example, for use dependencies). +
+IUSE_EFFECTIVE: is another + conceptual, unexported variable. Values in IUSE_EFFECTIVE are those which an ebuild + may legally use in queries about itself (for example, for the use function, and for use + in dependency specification conditional blocks). +
+USE: is a variable calculated by the package manager and exported to the ebuild + environment.

In all cases, the values of IUSE_REFERENCEABLE and IUSE_EFFECTIVE are undefined during +metadata generation. +

IUSE_REFERENCEABLE is equal to the calculated IUSE value. +

IUSE_EFFECTIVE contains the following values: +

All values in the calculated IUSE value. +
All possible values for the ARCH variable. +
All legal use flag names whose name starts with the lowercase equivalent of any value + in the profile USE_EXPAND variable followed by an underscore.

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. USE may contain other flag names that are not relevant for the +ebuild. + + +

12.1.2 REPLACING_VERSIONS and REPLACED_BY_VERSION

+ REPLACE-VERSION-VARS

In EAPIs listed in table 12.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 12.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. +

12.1.3 Offset-prefix variables EPREFIX, EROOT and ED

+ + +

Table 12.4: EAPIs supporting offset-prefix

+ + + + +

EAPI	Supports offset-prefix? +
0	No
1	No
2	No
3	Yes
4	Yes

+ + +

+ OFFSET-PREFIX-VARS

Table 12.4 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. +

12.2 The state of variables between functions

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 8.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 12.1. + + +

+ + +

Listing 12.1: Environment state between functions

+GLOBAL_VARIABLE="a" +
+
src_compile() +
{ +
    GLOBAL_VARIABLE="b" +
    DEFAULT_VARIABLE="c" +
    export EXPORTED_VARIABLE="d" +
    local LOCAL_VARIABLE="e" +
} +
+
src_install(){ +
    [[ ${GLOBAL_VARIABLE} == "a" ]] \ +
        || [[ ${GLOBAL_VARIABLE} == "b" ]] \ +
        || die "broken env saving for globals" +
+
    [[ ${DEFAULT_VARIABLE} == "c" ]] \ +
        || die "broken env saving for default" +
+
    [[ ${EXPORTED_VARIABLE} == "d" ]] \ +
        || die "broken env saving for exported" +
+
    [[ $(printenv EXPORTED_VARIABLE ) == "d" ]] \ +
        || die "broken env saving for exported" +
+
    [[ -z ${LOCAL_VARIABLE} ]] \ +
        || die "broken env saving for locals" +
} +

+ + +

12.3 Available commands

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. +

12.3.1 System commands

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. +

12.3.1.1 Guaranteed system commands

The following commands must always be available in the ebuild environment: +

All builtin commands in GNU bash, version 3.2⁶ . +
sed must be available, and must support all forms of invocations valid for GNU sed + version 4 or later. +
patch must be available, and must support all inputs valid for GNU patch.

12.3.2 Commands provided by package dependencies

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. Commands provided by dependencies are +available in the following cases: +

In the src phases, any command provided by a package listed in DEPEND is available. + + +
In the pkg phases, at least one of the following conditions must be met: +
- Any command provided by a package listed in DEPEND is available. +
- Any command provided by a package listed in RDEPEND is available.
+

12.3.3 Ebuild-specific Commands

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. +

12.3.3.1 Failure behaviour and related commands

+ 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 12.5. +

The following commands affect this behaviour: +

+nonfatal

+ NONFATAL Executes the remainder of its arguments as a command, preserving the exit + status. If this results in a command being called that would normally abort the build + process due to a failure (but not due to an explicit die or assert call), instead a + non-zero exit status shall be returned. Only in EAPIs listed in table 12.5 as supporting + nonfatal.

+ + +

Table 12.5: EAPI Command Failure Behaviour

+ + + + +

EAPI	Command failure behaviour	Supports nonfatal? +
0	Non-zero exit	No
1	Non-zero exit	No
2	Non-zero exit	No
3	Non-zero exit	No
4	Aborts	Yes

+ + +

12.3.3.2 Banned commands

+ 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. +

+ + +

Table 12.6: Banned commands

+ + + + + +

EAPI	Command banned?
	dohard	dosed + +
0	No	No
1	No	No
2	No	No
3	No	No
4	Yes	Yes

+ + +

12.3.3.3 Sandbox commands

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. +

+addread: Add a directory to the permitted read list. +
+addwrite: Add a directory to the permitted write list. +
+addpredict: Add a directory to the predict list. Any write to a location in this list will be + denied, but will not trigger access violation messages or abort the build process. +
+adddeny: Add a directory to the deny list.

12.3.3.4 Package manager query commands

These commands are used to extract information about the host 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. +

+has_version: Takes exactly one package dependency specification as an argument. Returns + true if a package matching the atom is installed in ROOT, and false otherwise. +
+best_version: Takes exactly one package dependency specification as an argument. If a + matching package is installed, prints the category, package name and version of the + highest matching version.

12.3.3.5 Output commands

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. +

+einfo: Displays an informational message. +
+einfon: Displays an informational message without a trailing newline. + + +
+elog: Displays an informational message of slightly higher importance. The package manager + may choose to log elog messages by default where einfo messages are not, for example. +
+ewarn: Displays a warning message. Must not go to stdout. +
+eerror: Displays an error message. Must not go to stdout. +
+ebegin: Displays an informational message. Should be used when beginning a possibly + lengthy process, and followed by a call to eend. +
+eend: Indicates that the process begun with an ebegin message has completed. Takes + one fixed argument, which is a numeric return code, and an optional message in all + subsequent arguments. If the first argument is 0, print a success indicator; otherwise, + print the message followed by a failure indicator.

12.3.3.6 Error commands

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. +

+die: Displays a failure message provided in its first and only argument, and then aborts + the build process. die is not guaranteed to work correctly if called from a subshell + environment. +
+assert: Checks the value of the shell’s pipe status variable, and if any component is non-zero + (indicating failure), calls die with its first argument as a failure message.

12.3.3.7 Build commands

These commands are used during the 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

Calls the program’s ./configure script. This is designed to work with GNU + Autoconf-generated scripts. Any additional parameters passed to econf are passed + directly to ./configure. econf will look in the current working directory for a + configure script unless the ECONF_SOURCE environment variable is set, in which case it + is taken to be the directory containing it. econf must pass the following options to the + configure script: +

+ ECONF-OPTIONS

+ + +

--prefix must default to ${EPREFIX}/usr unless overridden by econf’s caller. +
--mandir must be ${EPREFIX}/usr/share/man +
--infodir must be ${EPREFIX}/usr/share/info +
--datadir must be ${EPREFIX}/usr/share +
--sysconfdir must be ${EPREFIX}/etc +
--localstatedir must be ${EPREFIX}/var/lib +
--host must be the value of the CHOST environment variable. +
--libdir must be set according to Algorithm 9. +
--disable-dependency-tracking, if the EAPI is listed in table 12.7 as using it. This + option will only be passed if the string disable-dependency-tracking occurs in + the output of configure --help.

Table 12.7: Extra econf arguments for EAPIs

+ + + +

EAPI	--disable-dependency-tracking? +
0	No
1	No
2	No
3	No
4	Yes

Note that the ${EPREFIX} component represents the same offset-prefix as described in + Table 12.1. It facilitates offset-prefix installations which is supported by EAPIs listed in + Table 12.3. 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. +

Algorithm 9: econf --libdir logic

+ + 1: let prefix=${EPREFIX}/usr +
2: if the caller specified --prefix=$p then + +
3: let prefix=$p + +
4: end if +
5: let libdir= + + +
6: if the ABI environment variable is set then + +
7: let libvar=LIBDIR_$ABI +
8: if the environment variable named by libvar is set then + +
9: let libdir=the value of the variable named by libvar + +
10: end if + +
11: end if +
12: if libdir is non-empty then + +
13: pass --libdir=$prefix/$libdir to configure + +
14: end if +

+emake

Calls the $MAKE program, or GNU make if the MAKE variable is unset. Any arguments given + are passed directly to the make command, as are the user’s chosen MAKEOPTS. Arguments + given to emake override user configuration. See also section 12.3.1.1. emake must be an + external program and cannot be a function or alias—it must be callable from e. g. xargs. + Failure behaviour is EAPI dependent as per section 12.3.3.1. +

+einstall

A shortcut for the command given in Listing 12.2. Any arguments given to einstall are + passed verbatim to emake, as shown. Failure behaviour is EAPI dependent as per + section 12.3.3.1. +

The variable ED is defined as in Table 12.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 12.3, hence EAPIs + lacking offset-prefix support should use D instead of ED in the command given in + Listing 12.2. +

Listing 12.2: einstall command

+ + +

+emake \ +
   prefix="${ED}"/usr \ +
   mandir="${ED}"/usr/share/man \ +
   infodir="${ED}"/usr/share/info \ +
   libdir="${ED}"/usr/$(get_libdir) \ +
   "$@" \ +
   install +

12.3.3.8 Installation commands

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. These +commands must all be external programs and not bash functions or aliases—that is, they must be +callable from xargs. Ebuilds must not run any of these commands once the current phase function +has returned. +

+dobin

Installs the given files into DESTTREE/bin, where DESTTREE defaults to /usr. Gives + the files mode 0755 and transfers file ownership to the superuser or its equivalent on + the system or installation at hand. For instance on Gentoo Linux in a non-offset-prefix + installation this ownership is root:root, while on an offset-prefix aware installation + this may be joe:users. Failure behaviour is EAPI dependent as per section 12.3.3.1. +

+doconfd

Installs the given config files into /etc/conf.d/, by default with file mode 0644. + This can be overridden by setting INSOPTIONS with the insopts function. Failure + behaviour is EAPI dependent as per section 12.3.3.1. +

+dodir

Creates the given directories, by default with file mode 0755. This can be overridden + by setting DIROPTIONS with the diropts function. Failure behaviour is EAPI + dependent as per section 12.3.3.1. +

+dodoc

+ DODOC Installs the given files into a subdirectory under /usr/share/doc/${PF}/ with file + mode 0644. The subdirectory is set by the most recent call to docinto. If docinto + has not yet been called, instead installs to the directory /usr/share/doc/${PF}/. For + EAPIs listed in table 12.8 as supporting -r, if the first argument is -r, any subsequent + arguments that are directories are installed recursively to the appropriate location; in + any other case, it is an error for a directory to be specified. Failure behaviour is EAPI + dependent as per section 12.3.3.1. +

+doenvd

Installs the given environment files into /etc/env.d/, by default with file mode + 0644. This can be overridden by setting INSOPTIONS with the insopts function. Failure + behaviour is EAPI dependent as per section 12.3.3.1. + + +

+doexe

Installs the given files into the directory specified by the most recent exeinto call, + by default with file mode 0755. This can be overridden by setting EXEOPTIONS with the + exeopts function. If exeinto has not yet been called, behaviour is undefined. Failure + behaviour is EAPI dependent as per section 12.3.3.1. +

+dohard

Takes two parameters. Creates a hardlink from the second to the first. In EAPIs + listed in table 12.6, this command is banned as per section 12.3.3.2. Failure behaviour + is EAPI dependent as per section 12.3.3.1. +

+dohtml

Installs the given HTML files into a subdirectory under /usr/share/doc/$PF/. The + subdirectory is html by default, but this can be overridden by setting the DOCDESTTREE + variable with the docinto function. Files to be installed automatically are determined by + extension and the default extensions are css, gif, htm, html, jpeg, jpg, js and png. These + default extensions can be extended or reduced (see below). The options that can be passed to + dohtml are as follows: +

+: -r — enables recursion into directories. +
+: -V — enables verbosity. +
+: -A — adds file type extensions to the default list. +
+: -a — sets file type extensions to only those specified. +
+: -f — list of files that are able to be installed. +
+: -x — list of directories that files will not be installed from (only used in conjunction + with -r). +
+: -p — sets a document prefix for installed files, not to be confused with the global + offset-prefix.

Failure behaviour is EAPI dependent as per section 12.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. +

+doinfo

Installs a GNU Info file into the /usr/share/info area with file mode 0644. Failure + behaviour is EAPI dependent as per section 12.3.3.1. +

+doinitd

Installs the given initscript files into /etc/init.d, by default with file mode 0755. This + can be overridden by setting EXEOPTIONS with the exeopts function. Failure behaviour is + EAPI dependent as per section 12.3.3.1. +

+doins

+ DOINS Takes any number of files as arguments and installs them into INSDESTTREE, by default + with file mode 0644. This can be overridden by setting INSOPTIONS with the insopts + function. If the first argument is -r, then operates recursively, descending into any directories + given. For EAPIs listed in table 12.9, doins must install symlinks as symlinks; for other + EAPIs, behaviour is undefined if any symlink is encountered. Failure behaviour is EAPI + dependent as per section 12.3.3.1. +

+dolib

For each argument, installs it into the appropriate library directory as determined by + + + Algorithm 10, by default with file mode 0644. This can be overridden by setting LIBOPTIONS + with the libopts function. Any symlinks are installed into the same directory as + relative links to their original target. Failure behaviour is EAPI dependent as per + section 12.3.3.1. +

+dolib.so

As for dolib except each file is installed with mode 0755. +

+dolib.a

As for dolib except each file is installed with mode 0644. +

Algorithm 10: Determining the library directory

+ + 1: if CONF_LIBDIR_OVERRIDE is set in the environment then + +
2: return CONF_LIBDIR_OVERRIDE + +
3: end if +
4: if CONF_LIBDIR is set in the environment then + +
5: let LIBDIR_default=CONF_LIBDIR + +
6: else + +
7: let LIBDIR_default=“lib” + +
8: end if +
9: if ABI is set in the environment then + +
10: let abi=ABI + +
11: else if DEFAULT_ABI is set in the environment then + +
12: let abi=DEFAULT_ABI + +
13: else + +
14: let abi=“default” + +
15: end if +
16: return the value of LIBDIR_$abi +

+doman

Installs a man page into the appropriate subdirectory of /usr/share/man depending upon + its apparent section suffix (e. g. foo.1 goes to /usr/share/man/man1/foo.1 with file mode + 0644. +

+ DOMAN-LANGS

In EAPIs listed in table 12.10 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 12.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 12.10, the -i18n option takes precedence over the language code in the + filename. +

+domo

Installs a .mo file with file mode 0644 into the appropriate subdirectory of + DESTTREE/share/locale, generated by taking the basename of the file, removing the + .* suffix, and appending /LC_MESSAGES. The name of the installed files is the + package name with .mo appended. Failure behaviour is EAPI dependent as per + section 12.3.3.1. +

+dosbin

As dobin, but installs to DESTTREE/sbin. +

+dosym

Creates a symbolic link named as for its second parameter, pointing to the first. If the + directory containing the new link does not exist, creates it. Failure behaviour is EAPI + dependent as per section 12.3.3.1. +

+fowners

Acts as for chown, but takes paths relative to the image directory. Failure behaviour is + EAPI dependent as per section 12.3.3.1. +

+fperms

Acts as for chmod, but takes paths relative to the image directory. Failure behaviour is + EAPI dependent as per section 12.3.3.1. +

+newbin

As for dobin, but takes two parameters. The first is the file to install; the second is the + new filename under which it will be installed. +

+newconfd

As for doconfd, but takes two parameters as for newbin. +

+newdoc

As above, for dodoc. +

+newenvd

As above, for doenvd. +

+newexe

As above, for doexe. +

+newinitd

As above, for doinitd. +

+newins

As above, for doins. +

+newlib.a

As above, for dolib.a. +

+newlib.so

As above, for dolib.so. +

+newman

As above, for doman. +

+newsbin

As above, for dosbin. +

+keepdir

Creates a directory as for dodir, and an empty file whose name starts with .keep in that + directory to ensure that the directory does not get removed by the package manager + should it be empty at any point. Failure behaviour is EAPI dependent as per + section 12.3.3.1. + + +

+ + +

Table 12.8: EAPIs supporting dodoc -r

+ + + + +

EAPI	Supports dodoc -r? +
0	No
1	No
2	No
3	No
4	Yes

+ + +

Table 12.9: EAPIs supporting symlinks for doins

+ + + + +

EAPI	doins supports symlinks? +
0	No
1	No
2	No
3	No
4	Yes

+ + +

Table 12.10: doman language support options for EAPIs

+ + + + + +

EAPI	Language detection by filename?	Option -i18n takes precedence? +
0	No	Not applicable
1	No	Not applicable
2	Yes	No
3	Yes	No
4	Yes	Yes

+ + +

12.3.3.9 Commands affecting install destinations

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. +

+into: Sets the value of DESTTREE for future invocations of the above utilities. Creates the + directory under ${ED} in offset-prefix aware EAPIs or under ${D} in offset-prefix + agnostic EAPIs, using install -d with no additional options, if it does not already + exist. Failure behaviour is EAPI dependent as per section 12.3.3.1. +
+insinto: Sets the value of INSDESTTREE for future invocations of the above utilities. May + create the directory, as specified for into. +
+exeinto: Sets the install path for doexe and newexe. May create the directory, as specified + for into. +
+docinto: Sets the install subdirectory for dodoc et al. May create the directory, as specified + for into. +
+insopts: Sets the options passed by doins et al. to the install command. +
+diropts: Sets the options passed by dodir et al. to the install command. +
+exeopts: Sets the options passed by doexe et al. to the install command. +
+libopts: Sets the options passed by dolib et al. to the install command. +

12.3.3.10 Commands affecting install compression

+ CONTROLLABLE-COMPRESS

In EAPIs listed in table 12.11 as supporting controllable compression, the package manager may +optionally compress a subset of the files under the ED directory in offset-prefix aware EAPIs or the +D directory in offset-prefix agnostic EAPIs. To control which directories may or may not be +compressed, the package manager shall maintain two lists: +

An inclusion list, which initially contains /usr/share/doc, /usr/share/info and + /usr/share/man. + + +
An exclusion list, which initially contains /usr/share/doc/${PF}/html.

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 in offset-prefix aware EAPIs or the D variable in offset-prefix agnostic +EAPIs prepended, then: +

If it is a directory, act as if every file or directory immediately under this directory + were in the inclusion list. +
If the item is a file, it may be compressed unless it has been excluded as described + below. +
If the item does not exist, it is ignored.

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 in offset-prefix aware EAPIs or the D variable in +offset-prefix agnostic EAPIs prepended, then: +

If it is a directory, act as if every file or directory immediately under this directory + were in the exclusion list. +
If the item is a file, it shall not be compressed. +
If the item does not exist, it is ignored.

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. +

+docompress: If the first argument is -x, add each of its subsequent arguments to the + exclusion list. Otherwise, add each argument to the inclusion list. Only available in + EAPIs listed in table 12.11 as supporting docompress.

+ + +

Table 12.11: EAPIs supporting controllable compression

+ + + + +

EAPI	Supports controllable compression?	Supports docompress? +
0	No	No
1	No	No
2	No	No
3	No	No
4	Yes	Yes

+ + +

12.3.3.11 Use List Functions

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. Ebuilds must not run any of these +functions in global scope. +

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 12.12. +

+use

Returns shell true (0) if the first argument (a USE flag name) is enabled, false otherwise. + If the flag name is prefixed with !, returns true if the flag is disabled, and false if it is + enabled. It is guaranteed that this command is quiet. +

+usev

The same as use, but also prints the flag name if the condition is met. +

+useq

Deprecated synonym for use. +

+use_with

+ USE-WITH Has one-, two-, and three-argument forms. The first argument is a USE flag + name, the second a configure option name (${opt}), defaulting to the same as the + first argument if not provided, and the third is a string value (${value}). For EAPIs + listed in table 12.13 as not supporting it, an empty third argument is treated as if it + weren’t provided. If the USE flag is set, outputs --with-${opt}=${value} if the third + argument was provided, and --with-${opt} otherwise. If the flag is not set, then it + outputs --without-${opt}. +

+use_enable

Works the same as use_with(), but outputs --enable- or --disable- + instead of --with- or --without-.

+ + +

Table 12.12: EAPI Behaviour for Use Queries not in IUSE_EFFECTIVE

+ + + + +

EAPI	Behaviour +
0	Undefined
1	Undefined
2	Undefined
3	Undefined
4	Error

+ + +

Table 12.13: EAPIs supporting empty third argument in use_with and use_enable

+ + + + +

EAPI	Supports empty third argument? +
0	No
1	No
2	No
3	No
4	Yes

+ + +

12.3.3.12 Text List Functions

These functions check whitespace-separated lists for a particular value. +

+has: Returns shell true (0) if the first argument (a word) is found in the list of subsequent + arguments, false otherwise. Guaranteed quiet. +
+hasv: The same as has, but also prints the first argument if found. +
+hasq: Deprecated synonym for has.

12.3.3.13 Misc Commands

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. +

+dosed

Takes any number of arguments, which can be files or sed expressions. For each + argument, if it names, relative to ED (offset-prefix aware EAPIs) or D (offset-prefix + agnostic EAPIs) a file which exists, then sed is run with the current expression on that + file. Otherwise, the current expression is set to the text of the argument. The initial + value of the expression is s:${ED}::g in offset-prefix aware EAPIs and s:${D}::g in + offset-prefix agnostic EAPIs. In EAPIs listed in table 12.6, this command is banned + as per section 12.3.3.2. Failure behaviour is EAPI dependent as per section 12.3.3.1. +

+unpack

Unpacks one or more source archives, in order, into the current directory. After + unpacking, must ensure that all filesystem objects inside the current working directory + (but not the current working directory itself) have permissions a+r,u+w,go-w and that + all directories under the current working directory additionally have permissions a+x. +

All arguments to unpack must be either a filename without path, in which case unpack + looks in DISTDIR for the file, or start with the string ./, in which case unpack uses the + argument as a path relative to the working directory. +

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: +

tar files (*.tar). Ebuilds must ensure that GNU tar installed. +
gzip-compressed tar files (*.tar.gz, *.tgz, *.tar.Z, *.tbz). Ebuilds must + ensure that GNU gzip and GNU tar are installed. + + +
bzip2-compressed tar files (*.tar.bz2, *.tbz2, *.tar.bz). Ebuilds must + ensure that bzip2 and GNU tar are installed. +
zip files (*.zip, *.ZIP, *.jar). Ebuilds must ensure that Info-ZIP Unzip is + installed. +
gzip files (*.gz, *.Z, *.z). Ebuilds must ensure that GNU gzip is installed. +
bzip2 files (*.bz, *.bz2). Ebuilds must ensure that bzip2 is installed. +
7zip files (*.7z, *.7Z). Ebuilds must ensure that P7ZIP is installed. +
rar files (*.rar, *.RAR). Ebuilds must ensure that RARLAB’s unrar is installed. +
LHA archives (*.LHA, *.LHa, *.lha, *.lhz). Ebuilds must ensure that the lha + program is installed. +
ar archives (*.a). Ebuilds must ensure that GNU binutils is installed. +
deb packages (*.deb). Ebuilds must ensure that the deb2targz program is installed + on those platforms where the GNU binutils ar program is not available and the + installed ar program is incompatible with GNU archives. Otherwise, ebuilds must + ensure that GNU binutils is installed. +
lzma-compressed files (*.lzma). Ebuilds must ensure that LZMA Utils is installed. +
lzma-compressed tar files (*.tar.lzma). Ebuilds must ensure that LZMA Utils + and GNU tar are installed. +
xz-compressed files (*.xz). Ebuilds must ensure that XZ Utils is installed. Only + for EAPIs listed in table 12.14 as supporting xz. +
xz-compressed tar files (*.tar.xz). Ebuilds must ensure that XZ Utils and GNU + tar are installed. Only for EAPIs listed in table 12.14 as supporting xz.

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. +

Table 12.14: unpack extensions for EAPIs

+ + + +

EAPI	.xz and .tar.xz? +
0	No
1	No
2	No
3	Yes
4	Yes

+inherit

See section 11.1. + + +

+default

+ DEFAULT-FUNC Calls the default_ function for the current phase (see section 10.1.17). Must not be + called if the default_ function does not exist for the current phase in the current EAPI. + Only available in EAPIs listed in table 12.15.

+ + +

Table 12.15: EAPIs supporting the default function

+ + + + +

EAPI	Supports default function? +
0	No
1	No
2	Yes
3	Yes
4	Yes

+ + +

12.3.3.14 Debug Commands

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. +

+debug-print: If in a special debug mode, the arguments should be outputted or recorded + using some kind of debug logging. +
+debug-print-function: Calls debug-print with $1: entering function as the first + argument and the remaining arguments as additional arguments. +
+debug-print-section: Calls debug-print with now in section $*.

12.3.3.15 Reserved Commands and Variables

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: +

abort +
dyn +
ebuild +
hook +
paludis +
portage +
prep

12.4 The state of the system between functions

For the sake of this section: +

+ + +

Variancy is any package manager action that modifies either ROOT or / in any way that + isn’t merely a simple addition of something that doesn’t alter other packages. This + includes any non-default call to any pkg phase function except pkg_setup, a merge of + any package or an unmerge of any package. +
As an exception, changes to DISTDIR do not count as variancy. +
The pkg_setup function may be assumed not to introduce variancy. Thus, ebuilds + must not perform variant actions in this phase.

The following exclusivity and invariancy requirements are mandated: +

No variancy shall be introduced at any point between a package’s pkg_setup being + started up to the point that that package is merged, except for any variancy introduced + by that package. +
There must be no variancy between a package’s pkg_setup and a package’s + pkg_postinst, except for any variancy introduced by that package. +
Any non-default pkg phase function must be run exclusively. +
Each phase function must be called at most once during the build process for any given + package.

+ + + + + + +

Chapter 13
Merging and Unmerging

Note: +In this chapter, file and regular file have their Unix meanings. +

13.1 Overview

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. +

13.2 Directories

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. +

13.2.1 Permissions

The owner, group and mode (including set*id and sticky bits) of the directory must be preserved, +except as follows: +

Any directory owned by the user used to perform the build must become owned by the + root user. +
Any directory whose group is the primary group of the user used to perform the build + must have its group be that of the root user.

On SELinux systems, the SELinux context must also be preserved. Other directory attributes, +including modification time, may be discarded. +

13.2.2 Empty Directories

+ + +

Behaviour upon encountering an empty directory is undefined. Ebuilds must not attempt to install +an empty directory. +

13.3 Regular Files

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. +

13.3.1 Permissions

The owner, group and mode (including set*id and sticky bits) of the file must be preserved, except +as follows: +

Any file owned by the user used to perform the build must become owned by the root + user. +
Any file whose group is the primary group of the user used to perform the build must + have its group be that of the root user. +
The package manager may reduce read and write permissions on executable files that + have a set*id bit set.

On SELinux systems, the SELinux context must also be preserved. Other file attributes may be +discarded. +

13.3.2 File modification times

+ MTIME-PRESERVE

In EAPIs listed in table 13.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. +

+ + +

Table 13.1: Preservation of file modification times (mtimes)

+ + + + +

EAPI	mtimes preserved? +
0	Undefined
1	Undefined
2	Undefined
3	Yes
4	Yes

+ + +

13.3.3 Configuration File Protection

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: +

+ 1.: If the directory containing the file to be merged is not listed in CONFIG_PROTECT, and is + not a subdirectory of any such directory, and if the file is not listed in CONFIG_PROTECT, + the file is merged normally. +
+ 2.: If the directory containing the file to be merged is listed in CONFIG_PROTECT_MASK, or + is a subdirectory of such a directory, or if the file is listed in CONFIG_PROTECT_MASK, + the file is merged normally. +
+ 3.: If no existing file with the intended filename exists, or the existing file has identical + content to the one being merged, the file is installed normally. +
+ 4.: Otherwise, prepend the filename with ._cfg0000_. If no file with the new name exists, + then the file is merged with this name. +
+ 5.: Otherwise, increment the number portion (to form ._cfg0001_<name>) and repeat + step 4. Continue this process until a usable filename is found. +
+ 6.: If 9999 is reached in this way, behaviour is undefined.

13.4 Symlinks

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. +

13.4.1 Rewriting

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. + + +

13.5 Hard links

A hard link may be merged either as a single file with links or as multiple independent +files. +

13.6 Other Files

Ebuilds must not attempt to install any other type of file (FIFOs, device nodes etc). + + + + + + +

Chapter 14
Metadata Cache

14.1 Directory Contents

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. +

14.2 Cache File Format

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. +

+ 1.: Build-time dependencies (DEPEND) +
+ 2.: Run-time dependencies (RDEPEND) +
+ 3.: Slot (SLOT) +
+ 4.: Source tarball URIs (SRC_URI) +
+ 5.: RESTRICT +
+ 6.: Package homepage (HOMEPAGE) +
+ 7.: Package license (LICENSE) +
+ 8.: Package description (DESCRIPTION) +
+ 9.: Package keywords (KEYWORDS) +
+ 10.: Inherited eclasses (INHERITED) +
+ 11.: Use flags that this package respects (IUSE) +
+ 12.: Use flags that this package requires (REQUIRED_USE). Blank in some EAPIs; see + table 8.2. +
+ 13.: Post dependencies (PDEPEND) +
+ 14.: Old-style virtuals provided by this package (PROVIDE) +
+ 15.: The ebuild API version to which this package conforms (EAPI) + + +
+ 16.: Properties (PROPERTIES). In some EAPIs, may optionally be blank, regardless of ebuild + metadata; see table 8.2. +
+ 17.: Defined phases (DEFINED_PHASES). In some EAPIs, may optionally be blank, regardless + of ebuild metadata; see table 8.4. +
+ 18.: Blank lines to pad the file to 22 lines long

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. + + + + + + +

Chapter 15
Glossary

This section contains explanations of some of the terms used in this document whose meaning may +not be immediately obvious. +

+qualified package name: A package name along with its associated category. For example, + app-editors/vim is a qualified package name. +
+old-style virtual: An old-style virtual is a pseudo-package which exists if it is listed in an + ebuild’s PROVIDE variable. See chapter 6. +
+new-style virtual: A new-style virtual is a normal package in the virtual category which + installs no files and uses its dependency requirements to pull in a ‘provider’. This + is more flexible than the old-style virtuals described above, and requires no special + package manager code. +
+stand-alone repository: An (ebuild) repository which is intended to function on its own + as the only, or primary, repository on a system. Contrast with slave repository below. +
+slave repository, non-stand-alone repository: An (ebuild) repository which is not + complete enough to function on its own, but needs one or more master repositories to + satisfy dependencies and provide repository-level support files. Known in Portage as + an overlay. +
+master repository: See above. +

+ + + + + + + +

Appendix A
metadata.xml

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 the DTD file located at http://www.gentoo.org/dtd/metadata.dtd. + + + +

Appendix B
Unspecified Items

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 FEATURES variable. This is Portage specific. +
Similarly, any PORTAGE_ variable not explicitly listed. +
Any Portage configuration file. +
The VDB (/var/db/pkg). Ebuilds must not access this or rely upon it existing or being + in any particular format. +
The portageq command. The has_version and best_version commands are + available as functions. +
The emerge command. +
Binary packages. +
The PORTDIR_OVERLAY variable, and overlay behaviour in general.

+ + + +

Appendix C
Historical Curiosities

The items described in this chapter are included for information only. 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. +

C.1 If-else use blocks

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. +

This feature was deprecated and removed from the tree long before the introduction of +EAPI. + + +

+ + +

Listing C.1: If-else use blocks

+DEPEND=" +
    flag? ( +
        taken/if-true +
    ) : ( +
        taken/if-false +
    ) +
    " +
+

+ + +

C.2 cvs Versions

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. +

C.3 use.defaults

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. + + + + + + + +

Appendix D
Feature Availability by EAPI

Note: +This chapter is informative and for convenience only. Refer to the main text for specifics. + + + +

Table D.1: Features in EAPIs

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +



Feature	Reference	EAPIs
		0	1	2	3	4 +


						+
IUSE defaults	iuse-defaults p72	No	Yes	Yes	Yes	Yes
REQUIRED_USE	required-use p76	No	No	No	No	Yes
PROPERTIES	properties p76	Optionally	Optionally	Optionally	Optionally	Yes
RDEPEND=DEPEND	rdepend-depend p79	Yes	Yes	Yes	Yes	No
DEFINED_PHASES	defined-phases p82	Optionally	Optionally	Optionally	Optionally	Yes
SRC_URI arrows	src-uri-arrows p104	No	No	Yes	Yes	Yes
Slot dependencies	slot-deps p102	No	Yes	Yes	Yes	Yes
Use dependencies	use-deps p93	No	No	2-style	2-style	4-style
! blockers	bang-strength p99	Unspecified	Unspecified	Weak	Weak	Weak
!! blockers	bang-strength p99	Forbidden	Forbidden	Strong	Strong	Strong
S to WORKDIR fallback	s-workdir-fallback p107	Always	Always	Always	Always	Conditional
pkg_pretend	pkg-pretend p110	No	No	No	No	Yes
src_prepare	src-prepare p114	No	No	Yes	Yes	Yes
src_configure	src-configure p117	No	No	Yes	Yes	Yes
src_compile style	src-compile p121	0	1	2	2	2
src_install style	src-install p127	no-op	no-op	no-op	no-op	4
pkg_info	pkg-info p132	Installed	Installed	Installed	Installed	Both
default_ phase functions	default-phase-funcs p135	None	None	pkg_nofetch, +src_unpack, +src_prepare, +src_configure, +src_compile, +src_test	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
AA	aa p152	Yes	Yes	Yes	Yes	No
KV	kv p155	Yes	Yes	Yes	Yes	No

MERGE_TYPE	merge-type p156	No	No	No	No	Yes
REPLACING_VERSIONS	replace-version-vars p164	No	No	No	No	Yes
REPLACED_BY_VERSION	replace-version-vars p164	No	No	No	No	Yes
EPREFIX, ED, EROOT	offset-prefix-vars p167	No	No	No	Yes	Yes
Most utilities die	die-on-failure p171	No	No	No	No	Yes
nonfatal	nonfatal p171	No	No	No	No	Yes
dohard	banned-commands p174	Yes	Yes	Yes	Yes	Banned
dosed	banned-commands p174	Yes	Yes	Yes	Yes	Banned
econf arguments	econf-options p178					disable +dependency +tracking
dodoc -r	dodoc p181	No	No	No	No	Yes
doins handles symlinks	doins p182	No	No	No	No	Yes
doman languages	doman-langs p183	No	No	Yes	Yes	Yes
doman -i18n precedence	doman-langs p183	N/A	N/A	No	No	Yes
Controllable compression	controllable-compress p194	No	No	No	No	Yes
docompress	controllable-compress p194	No	No	No	No	Yes
use_with empty third arg	use-with p198	No	No	No	No	Yes
unpack support for xz?	unpack-extensions p204	No	No	No	Yes	Yes
default function	default-func p206	No	No	Yes	Yes	Yes
File mtimes preserved	mtime-preserve p214	Undefined	Undefined	Undefined	Yes	Yes

+ + + + + + +

Appendix E
Differences Between EAPIs

Note: +This chapter is informative and for convenience only. Refer to the main text for specifics. +

EAPI 0

EAPI 0 is the base EAPI. +

EAPI 1

EAPI 1 is EAPI 0 with the following changes: +

IUSE defaults, IUSE-DEFAULTS on page 72. +
Slot dependencies, SLOT-DEPS on page 102. +
Different src_compile implementation, SRC-COMPILE-1 on page 122.

EAPI 2

EAPI 2 is EAPI 1 with the following changes: +

Use dependencies, USE-DEPS on page 93. +
! and !! blockers, BANG-STRENGTH on page 99. +
SRC_URI arrows, SRC-URI-ARROWS on page 104. +
src_prepare, SRC-PREPARE on page 114. +
src_configure, SRC-CONFIGURE on page 117. +
Different src_compile implementation, SRC-COMPILE-2 on page 123. +
default_ phase functions for phases pkg_nofetch, src_unpack, src_prepare, + src_configure, src_compile and src_test; DEFAULT-PHASE-FUNCS on page 135. + + +
doman language detection by filename, DOMAN-LANGS on page 183. +
default function, DEFAULT-FUNC on page 206.

EAPI 3

EAPI 3 is EAPI 2 with the following changes: +

Offset-prefix support by definition of EPREFIX, ED and EROOT, OFFSET-PREFIX-VARS + on page 167. +
unpack supports .xz and .tar.xz, UNPACK-EXTENSIONS on page 204. +
File modification times are preserved, MTIME-PRESERVE on page 214.

EAPI 4

EAPI 4 is EAPI 3 with the following changes: +

PROPERTIES support is mandatory, PROPERTIES on page 76. +
REQUIRED_USE, REQUIRED-USE on page 76. +
RDEPEND=DEPEND no longer done, RDEPEND-DEPEND on page 79. +
DEFINED_PHASES support is mandatory, DEFINED-PHASES on page 82. +
Use dependency defaults, USE-DEP-DEFAULTS on page 102. +
S to WORKDIR fallback restricted, S-WORKDIR-FALLBACK on page 107. +
pkg_pretend, PKG-PRETEND on page 110. +
Default src_install no longer a no-op, SRC-INSTALL-4 on page 127. +
pkg_info can run on non-installed packages, PKG-INFO on page 132. +
AA is gone, AA on page 152. +
KV is gone, KV on page 155. +
MERGE_TYPE, MERGE-TYPE on page 156. +
REPLACING_VERSIONS and REPLACED_BY_VERSION, REPLACE-VERSION-VARS on + page 164. + + +
Utilities now die on failure, DIE-ON-FAILURE on page 171, unless called under + nonfatal, NONFATAL on page 171 +
dohard, dosed banned, BANNED-COMMANDS on page 174. +
econf adds --disable-dependency-tracking, ECONF-OPTIONS on page 178. +
dodoc -r support, DODOC on page 181. +
doins supports symlinks, DOINS on page 182. +
doman -i18n option takes precedence, DOMAN-LANGS on page 183. +
Controllable compression and docompress, CONTROLLABLE-COMPRESS on page 194. +
use_with and use_enable support empty third argument, USE-WITH on page 198.

+ + + + +

Bibliography

+ [1] Marius Mauch. GLEP 44: Manifest2 format. + http://glep.gentoo.org/glep-0044.html, December 2005. +

+ + + + + + -- cgit v1.2.3-65-gdbad