Package Manager Specification

+ id="x1-1000">Contents +

1 Introduction +href="#x1-90001" id="QQ2-1-9">Introduction
1.1 Aims and Motivation +href="#x1-100001.1" id="QQ2-1-10">Aims and Motivation
1.2 Rationale +href="#x1-110001.2" id="QQ2-1-11">Rationale
1.3 Conventions +href="#x1-120001.3" id="QQ2-1-12">Conventions
2 EAPIs +href="#x1-130002" id="QQ2-1-13">EAPIs
2.1 Definition +href="#x1-140002.1" id="QQ2-1-14">Definition
2.2 Defined EAPIs +href="#x1-150002.2" id="QQ2-1-15">Defined EAPIs
2.3 Reserved EAPIs +href="#x1-160002.3" id="QQ2-1-16">Reserved EAPIs
3 Names and Versions +href="#x1-170003" id="QQ2-1-17">Names and Versions
3.1 Restrictions upon Names +href="#x1-180003.1" id="QQ2-1-18">Restrictions upon Names
  3.1.1 Category Names +href="#x1-190003.1.1" id="QQ2-1-19">Category names
  3.1.2 Package Names +href="#x1-210003.1.2" id="QQ2-1-21">Package names
  3.1.3 Slot Names +href="#x1-230003.1.3" id="QQ2-1-23">Slot names
  3.1.4 USE Flag Names +href="#x1-240003.1.4" id="QQ2-1-24">USE flag names
  3.1.5 Repository Names +href="#x1-260003.1.5" id="QQ2-1-26">Repository names
  3.1.6 Keyword Names +href="#x1-270003.1.6" id="QQ2-1-27">License names
  3.1.7 EAPI Names +href="#x1-280003.1.7" id="QQ2-1-28">Keyword names +
  3.1.8 EAPI names
3.2 Version Specifications +href="#x1-300003.2" id="QQ2-1-30">Version Specifications
3.3 Version Comparison +href="#x1-310003.3" id="QQ2-1-31">Version Comparison
3.4 Uniqueness of versions +href="#x1-320003.4" id="QQ2-1-39">Uniqueness of Versions
4 Tree Layout +href="#x1-330004" id="QQ2-1-40">Tree Layout
4.1 Top Level +href="#x1-340004.1" id="QQ2-1-41">Top Level
4.2 Category Directories +href="#x1-350004.2" id="QQ2-1-42">Category Directories
4.3 Package Directories +href="#x1-360004.3" id="QQ2-1-43">Package Directories
4.4 The Profiles Directory +href="#x1-370004.4" id="QQ2-1-44">The Profiles Directory
  4.4.1 The profiles.desc file +href="#x1-380004.4.1" id="QQ2-1-45">The profiles.desc file
  4.4.2 The thirdpartymirrors file +href="#x1-390004.4.2" id="QQ2-1-46">The thirdpartymirrors file
  4.4.3 use.desc and related files +href="#x1-400004.4.3" id="QQ2-1-47">use.desc and related files
  4.4.4 The updates directory +href="#x1-410004.4.4" id="QQ2-1-48">The updates directory
4.5 The Licenses Directory -
4.6 The Eclass Directory -
4.7 The Metadata Directory +href="#x1-420004.5" id="QQ2-1-49">The Licenses Directory +
4.6 The Eclass Directory +
4.7 The Metadata Directory
  4.7.1 The metadata cache +href="#x1-450004.7.1" id="QQ2-1-52">The metadata cache
5 Profiles +href="#x1-460005" id="QQ2-1-53">Profiles
5.1 General principles +href="#x1-470005.1" id="QQ2-1-54">General Principles
5.2 Files that make up a profile +href="#x1-480005.2" id="QQ2-1-55">Files That Make up a Profile
  5.2.1 The parent file +href="#x1-490005.2.1" id="QQ2-1-56">The parent file
  5.2.2 The eapi file +href="#x1-500005.2.2" id="QQ2-1-57">The eapi file
  5.2.3 deprecated +href="#x1-510005.2.3" id="QQ2-1-58">deprecated
  5.2.4 make.defaults +href="#x1-520005.2.4" id="QQ2-1-59">make.defaults
  5.2.5 Simple line-based files +href="#x1-530005.2.5" id="QQ2-1-60">Simple line-based files
  5.2.6 packages +href="#x1-540005.2.6" id="QQ2-1-61">packages
  5.2.7 packages.build +href="#x1-550005.2.7" id="QQ2-1-62">packages.build
  5.2.8 package.mask +href="#x1-560005.2.8" id="QQ2-1-63">package.mask
  5.2.9 package.provided +href="#x1-580005.2.9" id="QQ2-1-65">package.provided
  5.2.10 package.use +href="#x1-590005.2.10" id="QQ2-1-66">package.use
  5.2.11 USE masking and forcing +href="#x1-600005.2.11" id="QQ2-1-67">USE masking and forcing
5.3 Profile variables +href="#x1-610005.3" id="QQ2-1-70">Profile Variables
  5.3.1 Incremental Variables +href="#x1-620005.3.1" id="QQ2-1-71">Incremental variables
  5.3.2 Specific variables and their meanings +href="#x1-630005.3.2" id="QQ2-1-73">Specific variables and their meanings
6 Ebuild File Format +href="#x1-640006" id="QQ2-1-74">Ebuild File Format
7 Ebuild-defined Variables +href="#x1-650007" id="QQ2-1-76">Ebuild-defined Variables
7.1 Metadata invariance +href="#x1-670007.1" id="QQ2-1-78">Metadata Invariance
7.2 Mandatory Ebuild-defined Variables +href="#x1-680007.2" id="QQ2-1-79">Mandatory Ebuild-defined Variables
7.3 Optional Ebuild-defined Variables +href="#x1-690007.3" id="QQ2-1-80">Optional Ebuild-defined Variables
  7.3.1 EAPI +href="#x1-700007.3.1" id="QQ2-1-83">EAPI
  7.3.2 Keywords +href="#x1-710007.3.2" id="QQ2-1-84">Keywords
  7.3.3 RDEPEND value +href="#x1-720007.3.3" id="QQ2-1-85">RDEPEND value
7.4 Magic Ebuild-defined Variables +href="#x1-730007.4" id="QQ2-1-87">Magic Ebuild-defined Variables
8 Dependencies +href="#x1-760008" id="QQ2-1-91">Dependencies
8.1 Dependency Classes +href="#x1-770008.1" id="QQ2-1-92">Dependency Classes
8.2 Dependency Specification Format +href="#x1-780008.2" id="QQ2-1-94">Dependency Specification Format
  8.2.1 All-of Dependency Specifications +href="#x1-790008.2.1" id="QQ2-1-97">All-of dependency specifications
  8.2.2 Use-conditional Dependency Specifications +href="#x1-800008.2.2" id="QQ2-1-98">USE-conditional dependency specifications
  8.2.3 Any-of Dependency Specifications +href="#x1-810008.2.3" id="QQ2-1-99">Any-of dependency specifications
  8.2.4 Exactly-one-of Dependency Specifications +href="#x1-820008.2.4" id="QQ2-1-100">Exactly-one-of dependency specifications
  8.2.5 At-most-one-of Dependency Specifications +href="#x1-830008.2.5" id="QQ2-1-101">At-most-one-of dependency specifications
  8.2.6 Package Dependency Specifications +href="#x1-840008.2.6" id="QQ2-1-102">Package dependency specifications +
   8.2.6.1 Operators + + +
   8.2.6.2 Block operator +
   8.2.6.3 Slot dependencies +
   8.2.6.4 2-style and 4-style USE dependencies
  8.2.7 Use State Constraints +href="#x1-910008.2.7" id="QQ2-1-112">USE state constraints
  8.2.8 Restrict +href="#x1-920008.2.8" id="QQ2-1-113">Restrict
  8.2.9 Properties - - +href="#x1-930008.2.9" id="QQ2-1-114">Properties
  8.2.10 SRC_URI +href="#x1-940008.2.10" id="QQ2-1-115">SRC_URI
9 Ebuild-defined Functions +href="#x1-950009" id="QQ2-1-116">Ebuild-defined Functions
9.1 List of Functions +href="#x1-960009.1" id="QQ2-1-117">List of Functions
  9.1.1 Initial Working Directories +href="#x1-970009.1.1" id="QQ2-1-118">Initial working directories
  9.1.2 pkg_pretend +href="#x1-980009.1.2" id="QQ2-1-120">pkg_pretend
  9.1.3 pkg_setup +href="#x1-990009.1.3" id="QQ2-1-122">pkg_setup
  9.1.4 src_unpack +href="#x1-1000009.1.4" id="QQ2-1-123">src_unpack
  9.1.5 src_prepare +href="#x1-1010009.1.5" id="QQ2-1-125">src_prepare
  9.1.6 src_configure +href="#x1-1020009.1.6" id="QQ2-1-128">src_configure
  9.1.7 src_compile +href="#x1-1030009.1.7" id="QQ2-1-131">src_compile
  9.1.8 src_test +href="#x1-1040009.1.8" id="QQ2-1-136">src_test
  9.1.9 src_install +href="#x1-1050009.1.9" id="QQ2-1-138">src_install
  9.1.10 pkg_preinst +href="#x1-1060009.1.10" id="QQ2-1-142">pkg_preinst
  9.1.11 pkg_postinst +href="#x1-1070009.1.11" id="QQ2-1-143">pkg_postinst
  9.1.12 pkg_prerm +href="#x1-1080009.1.12" id="QQ2-1-144">pkg_prerm
  9.1.13 pkg_postrm +href="#x1-1090009.1.13" id="QQ2-1-145">pkg_postrm
  9.1.14 pkg_config +href="#x1-1100009.1.14" id="QQ2-1-146">pkg_config
  9.1.15 pkg_info +href="#x1-1110009.1.15" id="QQ2-1-147">pkg_info
  9.1.16 pkg_nofetch +href="#x1-1120009.1.16" id="QQ2-1-149">pkg_nofetch
  9.1.17 default_ Phase Functions +href="#x1-1130009.1.17" id="QQ2-1-150">Default phase functions
9.2 Call Order +href="#x1-1140009.2" id="QQ2-1-152">Call Order
10 Eclasses +href="#x1-11500010" id="QQ2-1-153">Eclasses
10.1 The inherit command +href="#x1-11600010.1" id="QQ2-1-154">The inherit Command
10.2 Eclass-defined Metadata Keys +href="#x1-11700010.2" id="QQ2-1-155">Eclass-defined Metadata Keys
10.3 EXPORT_FUNCTIONS +href="#x1-11800010.3" id="QQ2-1-156">EXPORT_FUNCTIONS
11 The Ebuild Environment +href="#x1-11900011" id="QQ2-1-158">The Ebuild Environment
11.1 Defined Variables +href="#x1-12000011.1" id="QQ2-1-159">Defined Variables
  11.1.1 USE and IUSE Handling +href="#x1-12100011.1.1" id="QQ2-1-165">USE and IUSE handling
  11.1.2 REPLACING_VERSIONS and REPLACED_BY_VERSION +href="#x1-12200011.1.2" id="QQ2-1-166">REPLACING_VERSIONS and REPLACED_BY_VERSION
  11.1.3 Offset-prefix variables EPREFIX, EROOT and ED +href="#x1-12300011.1.3" id="QQ2-1-167">Offset-prefix variables
11.2 The state of variables between functions +href="#x1-12400011.2" id="QQ2-1-169">The State of Variables Between Functions
11.3 Available commands +href="#x1-12600011.3" id="QQ2-1-172">Available Commands
  11.3.1 System commands +href="#x1-12700011.3.1" id="QQ2-1-173">System commands + + +
   11.3.1.1 Guaranteed system commands +
   11.3.1.2 Shell options
  11.3.2 Commands provided by package dependencies +href="#x1-13000011.3.2" id="QQ2-1-177">Commands provided by package dependencies
  11.3.3 Ebuild-specific Commands +href="#x1-13100011.3.3" id="QQ2-1-178">Ebuild-specific commands +
   11.3.3.1 Failure behaviour and related commands +
   11.3.3.2 Banned commands +
   11.3.3.3 Sandbox commands +
   11.3.3.4 Package manager query commands +
   11.3.3.5 Output commands +
   11.3.3.6 Error commands +
   11.3.3.7 Patch commands +
   11.3.3.8 Build commands +
   11.3.3.9 Installation commands +
   11.3.3.10 Commands affecting install destinations +
   11.3.3.11 Commands affecting install compression +
   11.3.3.12 USE list functions +
   11.3.3.13 Text list functions +
   11.3.3.14 Misc commands +
   11.3.3.15 Debug commands +
   11.3.3.16 Reserved commands and variables
11.4 The state of the system between functions +href="#x1-14800011.4" id="QQ2-1-219">The State of the System Between Functions
12 Merging and Unmerging +href="#x1-14900012" id="QQ2-1-220">Merging and Unmerging
12.1 Overview +href="#x1-15100012.1" id="QQ2-1-222">Overview
12.2 Directories - - +href="#x1-15200012.2" id="QQ2-1-223">Directories
  12.2.1 Permissions +href="#x1-15300012.2.1" id="QQ2-1-224">Permissions
  12.2.2 Empty Directories +href="#x1-15400012.2.2" id="QQ2-1-225">Empty directories
12.3 Regular Files +href="#x1-15500012.3" id="QQ2-1-226">Regular Files
  12.3.1 Permissions +href="#x1-15600012.3.1" id="QQ2-1-227">Permissions
  12.3.2 File modification times +href="#x1-15700012.3.2" id="QQ2-1-228">File modification times
  12.3.3 Configuration File Protection +href="#x1-15800012.3.3" id="QQ2-1-230">Configuration file protection
12.4 Symlinks +href="#x1-15900012.4" id="QQ2-1-231">Symlinks
  12.4.1 Rewriting +href="#x1-16000012.4.1" id="QQ2-1-232">Rewriting
12.5 Hard links +href="#x1-16100012.5" id="QQ2-1-233">Hard Links
12.6 Other Files +href="#x1-16200012.6" id="QQ2-1-234">Other Files
13 Metadata Cache +href="#x1-16300013" id="QQ2-1-235">Metadata Cache
13.1 Directory Contents +href="#x1-16400013.1" id="QQ2-1-236">Directory Contents
13.2 Cache File Format +href="#x1-16500013.2" id="QQ2-1-237">Cache File Format
14 Glossary +href="#x1-16600014" id="QQ2-1-238">Glossary
Bibliography +href="#Q1-1-240">Bibliography + +
A metadata.xml +href="#x1-168000A" id="QQ2-1-241">metadata.xml
B Unspecified Items +href="#x1-169000B" id="QQ2-1-242">Unspecified Items
C Historical Curiosities -
C.1 If-else use blocks -
C.2 cvs Versions -
C.3 use.defaults -
C.4 Old-style Virtuals +href="#x1-170000C" id="QQ2-1-243">Historical Curiosities +
If-else USE Blocks +
cvs Versions +
use.defaults +
Old-style Virtuals
D Feature Availability by EAPI +href="#x1-175000D" id="QQ2-1-249">Feature Availability by EAPI
E Differences Between EAPIs +href="#x1-177000E" id="QQ2-1-252">Differences Between EAPIs +
EAPI 0 +
EAPI 1 +
EAPI 2 +
EAPI 3 +
EAPI 4 +
EAPI 5 +
EAPI 6
F Desk Reference +href="#x1-186000F" id="QQ2-1-261">Desk Reference

List of Algorithms

+ id="x1-2000">List of Algorithms +

3.1 Version comparison top-level logic +href="#x1-31001r1">Version comparison top-level logic
3.2 Version comparison logic for numeric components +href="#x1-31008r2">Version comparison logic for numeric components
3.3 Version comparison logic for each numeric component after the first +href="#x1-31025r3">Version comparison logic for each numeric component after the first
3.4 Version comparison logic for letter components +href="#x1-31041r4">Version comparison logic for letter components
3.5 Version comparison logic for suffixes +href="#x1-31049r5">Version comparison logic for suffixes
3.6 Version comparison logic for each suffix +href="#x1-31069r6">Version comparison logic for each suffix
3.7 Version comparison logic for revision components +href="#x1-31083r7">Version comparison logic for revision components
5.1 USE masking logic +href="#x1-60002r1">USE masking logic
11.1 eapply logic +href="#x1-138001r1">eapply logic
11.2 econf --libdir logic +href="#x1-139002r2">econf --libdir logic
11.3 Determining the library directory +href="#x1-140001r3">Determining the library directory
11.4 einstalldocs logic +href="#x1-145003r4">einstalldocs logic
11.5 get_libdir logic +href="#x1-145025r5">get_libdir logic

List of Listings

+ id="x1-3000">List of Listings +

9.1 src_unpack +href="#x1-100001r1">src_unpack
9.2 src_prepare, format 6 +href="#x1-101001r2">src_prepare, format 6
9.3 src_configure +href="#x1-102001r3">src_configure
9.4 src_compile, format 0 +href="#x1-103001r4">src_compile, format 0
9.5 src_compile, format 1 +href="#x1-103002r5">src_compile, format 1
9.6 src_compile, format 2 +href="#x1-103003r6">src_compile, format 2
9.7 src_install, format 4 +href="#x1-105001r7">src_install, format 4
9.8 src_install, format 6 +href="#x1-105002r8">src_install, format 6
10.1 EXPORT_FUNCTIONS example: foo.eclass +href="#x1-118001r1">EXPORT_FUNCTIONS example: foo.eclass
11.1 Environment state between functions +href="#x1-125001r1">Environment state between functions
11.2 einstall command +href="#x1-139017r2">einstall command
C.1 If-else use blocks +href="#x1-171001r1">If-else use blocks

List of Tables

5.1 Profile directory support for masking/forcing use flags in stable versions + id="x1-4000">List of Tables +

5.1 Profile directory support for masking/forcing use flags in stable versions only
5.2 Profile-defined Profile-defined IUSE injection for EAPIs
6.1 Bash version
7.1 EAPIs supporting +href="#x1-64001r1">Bash version
7.1 EAPIs supporting IUSE defaults
7.2 EAPIs supporting various ebuild-defined variables
7.3 EAPIs with +href="#x1-69002r2">EAPIs supporting various ebuild-defined variables
7.3 EAPIs with RDEPEND=DEPEND Default
7.4 EAPIs supporting RDEPEND=DEPEND default
7.4 EAPIs supporting DEFINED_PHASES
8.1 Dependency classes +href="#x1-77001r1">Dependency classes required to be satisfied for a particular phase function
8.2 EAPIs supporting EAPIs supporting SRC_URI arrows
8.3 EAPIs supporting EAPIs supporting REQUIRED_USE ?? groups
8.4 Support for Support for SLOT dependencies and sub-slots in EAPIs
8.5 EAPIs supporting EAPIs supporting USE dependencies
8.6 Exclamation mark +href="#x1-87001r6">Exclamation mark strengths for EAPIs
9.1 EAPIs with EAPIs with S to WORKDIR fallbacks
9.2 EAPIs supporting +href="#x1-98001r2">EAPIs supporting pkg_pretend
9.3 src_prepare support and behaviour for EAPIs
9.4 EAPIs -supporting EAPIs supporting +src_configure
9.5 src_compile behaviour for EAPIs
9.6 src_test -behaviour for EAPIs
9.7 src_test behaviour for +EAPIs
9.7 src_install behaviour for EAPIs
9.8 EAPIs supporting -pkg_info on non-installed packages
9.9 EAPIs supporting EAPIs supporting pkg_info on +non-installed packages
9.9 EAPIs supporting default_ phase functions
11.1 Defined variables
11.2 EAPIs supporting various added env variables
11.3 EAPIs -supporting various removed env variables
11.4 EAPIs supporting offset-prefix env -variables
11.5 Locale settings for EAPIs
11.6 EAPIs supporting offset-prefix
11.7 System -commands for EAPIs
11.8 EAPI Command Failure Behaviour
11.9 Banned -commands
11.10 EAPIs supporting -n for Defined +variables
11.2 EAPIs supporting various added env variables
11.3 EAPIs supporting +various removed env variables
11.4 EAPIs supporting offset-prefix env variables
11.5 Locale +settings for EAPIs
11.6 EAPIs supporting offset-prefix
11.7 System commands for +EAPIs
11.8 EAPI command failure behaviour
11.9 Banned commands
11.10 EAPIs +supporting --host-root for *_version commands
11.11 EAPIs supporting -n for +die and assert commands
11.11 Patch -commands for EAPIs
11.12 Extra econf arguments for EAPIs
11.13 EAPIs supporting -dodoc -r
11.14 EAPIs supporting assert commands
11.12 Patch commands for EAPIs
11.13 Extra econf +arguments for EAPIs
11.14 EAPIs supporting dodoc -r
11.15 EAPIs supporting +doheader and newheader
11.15 EAPIs supporting -symlinks for doins
11.16 doman language support options for EAPIs
11.17 EAPIs -supporting stdin for new* commands
11.18 EAPIs supporting --host-root for *_version +class="ectt-1000">newheader
11.16 EAPIs supporting symlinks for doins
11.17 doman +language support options for EAPIs
11.18 EAPIs supporting stdin for new* commands
11.19 EAPIs supporting controllable compression
11.20 EAPI Behaviour for -Use Queries not in IUSE_EFFECTIVE
11.21 EAPIs supporting empty third argument -in EAPIs supporting controllable compression
11.20 EAPI behaviour for +use queries not in IUSE_EFFECTIVE
11.21 EAPIs supporting empty third argument in +use_with and use_enable
11.22 EAPIs supporting EAPIs supporting usex and in_iuse
11.23 unpack behaviour for EAPIs
11.24 unpack extensions for EAPIs
11.25 Misc commands for +href="#x1-145034r25">Misc commands for EAPIs
12.1 Preservation of file modification times (mtimes)
D.1 Features in EAPIs
+href="#x1-157001r1">Preservation of file modification times (mtimes)
D.1 Features in EAPIs

+ + +

Acknowledgements

Thanks to Mike Kelly (package manager provided utilities, section 11.3.3), Danny van Dyk (ebuild + id="x1-6000">Acknowledgements +

Thanks to Mike Kelly (package manager provided utilities, section 11.3.3), Danny van Dyk (ebuild functions, section 9), David Leverton (various sections), Petteri Räty (environment state, +href="#x1-950009">9), David Leverton (various sections), Petteri Räty (environment state, section 11.2) and Michał Górny (various sections) for contributions. Thanks also to +href="#x1-12400011.2">11.2) and Michał Górny (various sections) for contributions. Thanks also to Mike Frysinger and Brian Harring for proof-reading and suggestions for fixes and/or clarification. -

Copyright and Licence

This document is released under the Creative Commons Attribution-Share Alike 3.0 Licence. The + id="x1-7000">Copyright and Licence +

The bulk of this document is © 2007–2017 Stephen Bennett, Christian Faulhammer, Ciaran +McCreesh and Ulrich Müller. Contributions are owned by their respective authors, and may have +been changed substantially before inclusion. +

This document is released under the Creative Commons Attribution-Share Alike 3.0 Licence. The full text of this licence can be found at http://creativecommons.org/licenses/by-sa/3.0/. -

Reporting Issues

Issues (inaccuracies, wording problems, omissions etc.) in this document should be reported via + id="x1-8000">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

Patches (in git format-patch form if possible) may be submitted either via Bugzilla or to the gentoo-pms@lists.gentoo.org mailing list. Patches will be reviewed by the PMS team, who will do one of the following: -

Accept and apply the patch.
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 + + +

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 +

If any issue cannot be resolved by the PMS team, it may be escalated to the Gentoo Council. @@ -565,9 +647,9 @@ Council.

Chapter 1
Introduction

+ id="x1-90001">Introduction

1.1 Aims and Motivation

+ id="x1-100001.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. @@ -575,12 +657,12 @@ repository. class="ecti-1000">not designed to be an introduction to ebuild development. Prior knowledge of ebuild creation and an understanding of how the package management system works is assumed; certain less familiar terms are explained in the Glossary in chapter 14. +href="#x1-16600014">14.

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

1.2 Rationale

+ id="x1-110001.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 @@ -595,7 +677,7 @@ incompatibilities with any particular repository.

1.3 Conventions

+ id="x1-120001.3">Conventions

Text in teletype is used for filenames or variable names. Italic text is used for terms with a @@ -613,12 +695,12 @@ repositories.

Chapter 2
EAPIs

+ id="x1-130002">EAPIs

2.1 Definition

+ id="x1-140002.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 as per section 3.1.7, and is part of an ebuild’s metadata. +href="#x1-290003.1.8">3.1.8, and is part of an ebuild’s metadata.

If a package manager encounters a package version with an unrecognised EAPI, it must not attempt to perform any operations upon it. It could, for example, ignore the package version entirely (although this can lead to user confusion), or it could mark the package version as masked. @@ -627,11 +709,11 @@ 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. +href="#x1-500005.2.2">5.2.2.

2.2 Defined EAPIs

+ id="x1-150002.2">Defined EAPIs

The following EAPIs are defined by this specification:

EAPI ‘6’ contains a number of extensions to EAPI Except where explicitly noted, everything in this specification applies to all of the above EAPIs.¹ + id="x1-15001f1"> 2.3 Reserved EAPIs + id="x1-160002.3">Reserved EAPIs @@ -686,22 +768,22 @@ class="ectt-1000">paludis- are reserved for experimental use Chapter 3 Names and Versions + id="x1-170003">Names and Versions 3.1 Restrictions upon Names + id="x1-180003.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 + id="x1-190003.1.1">Category names A category name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a hyphen, a dot or a plus sign. Note: A hyphen is not required because of the 3.1.2 Package Names + id="x1-210003.1.2">Package names A package name may contain any of the characters [A-Za-z0-9+_-]. It must not begin with a hyphen or a plus sign, and must not end in a hyphen followed by anything matching the version syntax described in section 3.2. +href="#x1-300003.2">3.2. Note: A package name does not include the category. The term qualified package name is used where a @@ -727,7 +809,7 @@ class="ectt-1000">category/package pair is meant. 3.1.3 Slot Names + id="x1-230003.1.3">Slot names A slot name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a hyphen, a dot or a plus sign. @@ -736,60 +818,65 @@ a dot or a plus sign. 3.1.4 USE Flag Names + id="x1-240003.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 11.1.1. +href="#x1-12100011.1.1">11.1.1. Note: The at-sign is required for LINGUAS. 3.1.5 Repository Names + id="x1-260003.1.5">Repository names A repository name may contain any of the characters [A-Za-z0-9_-]. It must not begin with a hyphen. In addition, every repository name must also be a valid package name. 3.1.6 Keyword Names - A keyword name may contain any of the characters [License names + A license name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a +hyphen, a dot or a plus sign. + + + 3.1.7 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. - + - 3.1.7 EAPI Names - An EAPI name may contain any of the characters [3.1.8 EAPI names + An EAPI name may contain any of the characters [A-Za-z0-9+_.-]. It must not begin with a hyphen, a dot or a plus sign. - + + + 3.2 Version Specifications - The package manager must not impose fixed limits upon the number of version components. + id="x1-300003.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 + 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 This may optionally be followed by one of [a-z] (a lowercase letter). - - - This may be followed by zero or more of the suffixes This may be followed by zero or more of the suffixes _alpha, _beta, _pre, _rc or _p, which themselves may be followed by an optional integer. Suffix and integer count as separate version components. - This may optionally be followed by the suffix 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 + id="x1-310003.3">Version Comparison + Version specifications are compared component by component, moving from left to right, as detailed in Algorithm 3.1 and sub-algorithms. If a sub-algorithm returns a decision, then that is +href="#x1-31001r1">3.1 and sub-algorithms. If a sub-algorithm returns a decision, then that is the result of the whole comparison; if it terminates without returning a decision, the process continues from the point from which it was invoked. - Algorithm 3.1: Version comparison top-level logic +class="content">Version comparison top-level logic - 1: let + 1: let A and B be the versions to be compared - 2: compare numeric components using Algorithm 3.2 - 3: compare letter components using Algorithm 3.4 - 4: compare suffixes using Algorithm 3.5 - 5: compare revision components using Algorithm 3.7 - 6: + 2: compare numeric components using Algorithm 3.2 + 3: compare letter components using Algorithm 3.4 + 4: compare suffixes using Algorithm 3.5 + 5: compare revision components using Algorithm 3.7 + 6: return A = B - Algorithm 3.2: Version comparison logic for numeric components +class="content">Version comparison logic for numeric components - 1: define the notations + 1: define the notations An_k and Bn_{A and B respectively, using 0-based indexing - 2: + 2: if An₀ > Bn₀ using integer comparison then - 3: + 3: return A > B - 4: + 4: else if An_{< Bn₀ using integer comparison then - 5: + 5: return A < B - 6: + 6: end if - 7: let + 7: let Ann be the number of numeric components of A - 8: let + 8: let Bnn be the number of numeric components of B - 9: + 9: for all i such that i i < Ann and i < Bnn, in ascending order do - 10: compare + 10: compare An_i and Bn_i using Algorithm 3.3 +href="#x1-31025r3">3.3 - 11: + 11: end for - 12: + 12: if Ann > Bnn then - 13: + 13: return A > B - 14: + 14: else if Ann < Bnn then - 15: + 15: return A if - Algorithm 3.3: Version comparison logic for each numeric component after the first +class="content">Version comparison logic for each numeric component after the first - 1: + 1: if either An_i or i has a leading 0 then - 2: let + 2: let An′_i be An_i with any trailing 0s removed - 3: let + 3: let Bn′_i be Bn_i with any trailing 0s removed - 4: + 4: if An′_{′_i using ASCII stringwise comparison then - 5: + 5: return A > B - 6: + 6: else if An′_i using ASCII stringwise comparison then - 7: + 7: return A Bn_i using integer comparison then - 11: + 11: return A > B - 12: + 12: else if An_{< Bn_i using integer comparison then - 13: + 13: return A if - Algorithm 3.4: Version comparison logic for letter components +class="content">Version comparison logic for letter components - 1: let + 1: let Al be the letter component of A if any, otherwise the empty string - 2: let + 2: let Bl be the letter component of B if any, otherwise the empty string - 3: + 3: if Al > Bl using ASCII stringwise comparison then - 4: + 4: return A > B - 5: + 5: else if Al < Bl using ASCII stringwise comparison then - 6: + 6: return A if - Algorithm 3.5: Version comparison logic for suffixes +class="content">Version comparison logic for suffixes - 1: define the notations + 1: define the notations As_k and Bs_{A and B respectively, using 0-based indexing - 2: let + 2: let Asn be the number of suffixes of A - 3: let + 3: let Bsn be the number of suffixes of B - 4: + 4: for all i such that i i < Asn and i < Bsn, in ascending order do - 5: compare + 5: compare As_i and Bs_i using Algorithm 3.6 +href="#x1-31069r6">3.6 - 6: + 6: end for - 7: + 7: if Asn > Bsn then - 8: + 8: if As_Bsn is of type _p then - 9: + 9: return A > B - 10: + 10: else - 11: + 11: return A B - 18: + 18: end if - 19: + 19: end if} @@ -1307,18 +1371,18 @@ class="ecbx-1000">if - Algorithm 3.6: Version comparison logic for each suffix +class="content">Version comparison logic for each suffix - 1: + 1: if As_i and _alpha vs _beta etc) then - 2: let + 2: let As′_i be the integer part of As_i if any, otherwise 0 - 3: let + 3: let Bs′_i be the integer part of Bs_i if any, otherwise 0 - 4: + 4: if As′_{′_i, using integer comparison then - 5: + 5: return A > B - 6: + 6: else if As′_i, using integer comparison then - 7: + 7: return A B - 11: + 11: else - 12: + 12: return A if - Algorithm 3.7: Version comparison logic for revision components +class="content">Version comparison logic for revision components - 1: let + 1: let Ar be the integer part of the revision component of A if any, otherwise 0 - 2: let + 2: let Br be the integer part of the revision component of B if any, otherwise 0 - 3: + 3: if Ar > Br using integer comparison then - 4: + 4: return A > B - 5: + 5: else if Ar if 3.4 Uniqueness of versions - No two packages in a given repository may have the same qualified package name and equal + id="x1-320003.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.000.2. Chapter 4 Tree Layout + id="x1-330004">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 + id="x1-340004.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. +href="#x1-350004.2">4.2. A profiles directory, described in section 4.4. +href="#x1-370004.4">4.4. A licenses directory (optional), described in section 4.5. +href="#x1-420004.5">4.5. An eclass directory (optional), described in section 4.6. +href="#x1-430004.6">4.6. A metadata directory (optional), described in section 4.7. +href="#x1-440004.7">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 @@ -1537,20 +1597,20 @@ href="#x1-420004.7">4.7. 4.2 Category Directories + id="x1-350004.2">Category Directories Each category provided by the repository (see also: the profiles/categories file, section 4.4) +href="#x1-370004.4">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. +href="#x1-168000A">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 +href="#x1-360004.3">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 4.3 Package Directories + id="x1-360004.3">Package Directories A package directory contains the following: Zero or more ebuilds. These are as described in section 6 and others. +href="#x1-640006">6 and others. A metadata.xml file, as described in appendix A. Optional only for legacy support. +href="#x1-168000A">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]. +href="#XGlep44">2]. Can be omitted if the file would be + empty. 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 + Any ebuild in a package directory must be named name-ver.ebuild, where name is the +(unqualified) package name, and ver is the package’s version. Package managers must ignore any +ebuild file that does not match these rules. + A package directory that contains no correctly named ebuilds shall be considered a package with no versions. A package with no versions shall be considered equivalent to a package that does not exist (and by extension, a package manager may treat a package that does not exist as a package with no versions). - A package directory may contain other files or directories, whose purpose is not covered by this + 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 + id="x1-370004.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 The profiles directory may contain an eapi file. This file, if it exists, must contain a single line with the name of an EAPI. This specifies the EAPI to use when handling the profiles directory; a package manager must not attempt to use any repository whose profiles directory requires an EAPI it does not support. If no eapi file is present, EAPI 0 shall be used. - If the repository is not intended to be stand-alone, the contents of these files are to be taken from + 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 + 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 ARCH variable, categories: Contains a list, one entry per line, of categories provided by this repository. + +
eapi: Contains a list, one entry per line, of package dependency profiles.desc; Described below in section 4.4.1. +href="#x1-380004.4.1">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. +href="#x1-260003.1.5">3.1.5.
thirdpartymirrors: Described below in section 4.4.2. +href="#x1-390004.4.2">4.4.2.
use.desc: Contains descriptions of valid global USE flags for this repository. The format is described in section 4.4.3. +href="#x1-400004.4.3">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. +href="#x1-400004.4.3">4.4.3.
desc/: <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 4.4.3. The USE_EXPAND name is not included as a prefix here. @@ -1711,14 +1764,14 @@ class="ecti-1000">not included as updates/; This directory is described in section 4.4.4.

+href="#x1-410004.4.4">4.4.4. +

4.4.1 The profiles.desc file

The profiles.desc file +

profiles.desc is a line-based file, with the standard commenting rules from section 4.4, +href="#x1-370004.4">4.4, containing a list of profiles that are valid for use, along with their associated architecture and status. Each line has the format: @@ -1726,9 +1779,9 @@ status. Each line has the format:

Where: -

Where: +

<keyword> is the default keyword for the profile and the <stability> indicates the stability of th values stable and dev are widely used, but repositories may use other values.

Fields are whitespace-delimited. -

Fields are whitespace-delimited. +

4.4.2 The thirdpartymirrors file

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 @@ -1761,7 +1814,7 @@ is:

Fields are whitespace-delimited. When parsing a URI of the form

Fields are whitespace-delimited. When parsing a URI of the form mirror://name/path/filename, where the path/ part is optional, the 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 +

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 +

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 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: @@ -1789,8 +1842,8 @@ is:

use.local.desc contains descriptions of every valid local USE flag—those that apply only to a small number of packages, or that have different meanings for different packages. Its format is: @@ -1799,17 +1852,17 @@ is:

Flags must be listed once for each package to which they apply, or if a flag is listed in both +

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 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 move <qpn1> <qpn2>
slotmove <spec> <slot1> <slot2>

The first form, where

The first form, where qpn1 and qpn2 are qualified package names, instructs the package @@ -1832,41 +1885,41 @@ 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 +

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 +

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 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 7.3, and will contain the complete text of the license in human-readable form. Plain text +href="#x1-690007.3">7.3, 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 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 10. It may also contain, in their own directory, support files +href="#x1-11500010">10. It may also contain, in their own directory, support files needed by these eclasses. -

4.7 The Metadata Directory

The 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

4.7.1 The metadata cache

The 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 13. +href="#x1-16300013">13. @@ -1891,9 +1944,9 @@ href="#x1-16100013">13.

Chapter 5
Profiles

+ id="x1-460005">Profiles

5.1 General principles

+ id="x1-470005.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 @@ -1907,11 +1960,11 @@ profiles.

5.2 Files that make up a profile

+ id="x1-480005.2">Files That Make up a Profile

5.2.1 The parent file

+ id="x1-490005.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 @@ -1925,7 +1978,7 @@ encountering a cycle is undefined.

5.2.2 The eapi file

+ id="x1-500005.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 @@ -1939,7 +1992,7 @@ class="ectt-1000">parent file nor in subdirectories.

5.2.3 deprecated

+ id="x1-510005.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

5.2.4 make.defaults

+ id="x1-520005.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. +href="#x1-610005.3">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 make.defaults files.

5.2.5 Simple line-based files

These files are a simple one-item-per-line list, which is inherited in the following manner: the + id="x1-530005.2.5">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.6 packages

+ id="x1-540005.2.6">packages -

The

The packages file is used to define the ‘system set’ for this profile. After the above rules for inheritance and comments are applied, its lines must take one of two forms: a package dependency specification prefixed by * denotes that it forms part of the system set. A package dependency specification on its own may also appear for legacy reasons, but should be ignored when calculating the system set. -

5.2.7 packages.build

The 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.8 package.mask

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

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). +href="#x1-370004.4">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.9 package.provided

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.10 package.use

+ id="x1-590005.2.10">package.use -

The

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 @@ -2055,11 +2108,11 @@ 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.11 USE masking and forcing

This section covers the eight files USE masking and forcing +

This section covers the eight files use.mask, use.force, use.stable.mask, package.use.stable.mask, and package.use. stable.force. They are described together because they interact in a non-trivial manner. -

Simply speaking,

Simply speaking, use.mask and use.force are used to say that a given USE flag must never or always, respectively, be enabled when using this profile. package.use.mask and package.use.force do the same thing on a per-package, or per-version, basis. -

STABLEMASK In profile directories with an EAPI supporting stable masking, as listed in table 5.1, +

stablemask In profile directories with an EAPI supporting stable masking, as listed in table 5.1, the same is true for use.stable.mask, use.stable.force, package.use.stable.mask and package.use.stable.force. These files, however, only act on packages that are merged due to a stable keyword in the sense of subsection 7.3.2. Thus, these files can be used to restrict the feature +href="#x1-710007.3.2">7.3.2. Thus, these files can be used to restrict the feature set deemed stable in a package.

Table 5.1: Profile directory support for masking/forcing use flags in stable versions only

+class="content">Profile directory support for masking/forcing use flags in stable versions only

The precise manner in which the eight files interact is less simple, and is best described in terms of +

The precise manner in which the eight files interact is less simple, and is best described in terms of the algorithm used to determine whether a flag is masked for a given package version. This is described in Algorithm 5.1.

+href="#x1-60002r1">5.1.

Algorithm 5.1: USE masking logic

+class="content">USE masking logic

- 1: let masked = false -
2: + 1: let masked = false +
2: for each profile in the inheritance tree, depth first do -
3: +
3: if use.mask contains flag then -
4: let masked = true + id="x1-60006r87"> +
4: let masked = true -
5: +
5: else if use.mask contains -flag then -
6: let masked = false + id="x1-60008r89"> +
6: let masked = false -
7: +
7: end if -
8: +
8: if stable keyword in use then -
9: +
9: if use.stable.mask contains flag then -
10: let masked = true + id="x1-60012r93"> +
10: let masked = true -
11: +
11: else if use.stable.mask contains -flag then -
12: let masked = false + id="x1-60014r95"> +
12: let masked = false -
13: +
13: end if -
14: +
14: end if -
15: +
15: for each line in package.use.mask, in order, for which the spec matches package do -
16: +
16: if line contains flag then -
17: let masked = true + id="x1-60019r100"> +
17: let masked = true -
18: +
18: else if line contains -flag then -
19: let masked = false + id="x1-60021r102"> +
19: let masked = false -
20: +
20: end if -
21: +
21: end for -
22: +
22: if stable keyword in use then -
23: +
23: for each line in package.use.stable.mask, in order, for which the spec matches package do -
24: +
24: if line contains flag then -
25: let masked = true + id="x1-60027r108"> +
25: let masked = true -
26: +
26: else if line contains -flag then -
27: let masked = false + id="x1-60029r110"> +
27: let masked = false -
28: +
28: end if -
29: +
29: end for -
30: +
30: end if -
31: +
31: end for

@@ -2332,15 +2364,15 @@ class="ecbx-1000">for

Stable restrictions (“stable keyword in use” in Algorithm 5.1) are applied exactly if +

Stable restrictions (“stable keyword in use” in Algorithm 5.1) are applied exactly if replacing in KEYWORDS all stable keywords by the corresponding tilde prefixed keywords (see subsection 7.3.2) would result in the package installation being prevented due to the 7.3.2) would result in the package installation being prevented due to the KEYWORDS setting. -

The logic for

The logic for use.force, use.stable.force, package.use.force, and package.use. stable.force is identical. If a flag is both masked and forced, the mask is considered to take precedence. -

USE_EXPAND values may be forced or masked by using expand_name_value. -

A package manager may treat

A package manager may treat ARCH values that are not the current architecture as being masked.

5.3 Profile variables

+ id="x1-610005.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

+ id="x1-620005.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 @@ -2392,7 +2424,7 @@ class="ectt-1000">CONFIG_PROTECT

CONFIG_PROTECT_MASK

If the package manager supports any EAPI listed in table 5.2 as using profile-defined 5.2 as using profile-defined IUSE injection, the following variables must also be treated incrementally; otherwise, the following variables may or may not be treated incrementally: @@ -2416,14 +2448,14 @@ override those in parent profiles.

Table 5.2: Profile-defined IUSE injection for EAPIs

+class="ectt-1000">IUSE injection for EAPIs

5.3.2 Specific variables and their meanings

+ id="x1-630005.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 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 12.3.3. +href="#x1-15800012.3.3">12.3.3.
USE: 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 11.1.1 for details. +href="#x1-12100011.1.1">11.1.1 for details.
USE_EXPAND_UNPREFIXED: USE_EXPAND, but no prefix is used. If the repository contains any package using an EAPI supporting profile-defined IUSE injection (see table 5.2), this list must contain at least 5.2), this list must contain at least ARCH. See section 11.1.1 for +href="#x1-12100011.1.1">11.1.1 for details.
USE_EXPAND_HIDDEN: Contains a (possibly empty) subset of names from USE_ +class="description">Contains a (possibly empty) subset of names from EXPAND and USE_EXPAND_UNPREFIXED. The package manager may use this set as a hint - to avoid displaying uninteresting or unhelpful information to an end user. +class="ectt-1000">USE_EXPAND and USE_EXPAND_UNPREFIXED. The package manager may use this set as + a hint to avoid displaying uninteresting or unhelpful information to an end user.
USE_EXPAND_IMPLICIT, IUSE_IMPLICIT: Used to inject implicit values into IUSE. See section 11.1.1 for details.

+href="#x1-12100011.1.1">11.1.1 for details.

In addition, for EAPIs listed in table 5.2 as supporting profile defined 5.2 as supporting profile defined IUSE injection, the variables named in USE_EXPAND and USE_EXPAND_UNPREFIXED have special handling as described in section 11.1.1. +href="#x1-12100011.1.1">11.1.1.

Any other variables set in make.defaults must be passed on into the ebuild environment as-is, and are not required to be interpreted by the package manager. @@ -2531,21 +2562,20 @@ and are not required to be interpreted by the package manager.

Chapter 6
Ebuild File Format

+ id="x1-640006">Ebuild File Format

BASH-VERSION The ebuild file format is in its basic form a subset of the format of a bash script. +class="eccc1000-">bash-version The ebuild file format is in its basic form a subset of the format of a bash script. The interpreter is assumed to be GNU bash, version as listed in table 6.1, or any later version. If +href="#x1-64001r1">6.1, or any later version. If possible, the package manager should set the shell’s compatibility level to the exact version specified. It must ensure that any such compatibility settings (e.g. the BASH_COMPAT variable) are not exported to external programs.

The file encoding must be UTF-8 with Unix-style newlines. When sourced, the ebuild must define certain variables and functions (see sections 7 and 9 for specific information), and must not call +href="#x1-650007">7 and 9 for specific information), and must not call any external programs, write anything to standard output or standard error, or modify the state of the system in any way.

@@ -2553,13 +2583,13 @@ the system in any way.

Table 6.1: Bash version

+class="content">Bash version

Chapter 7
Ebuild-defined Variables

+ id="x1-650007">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 11.1. +href="#x1-12000011.1">11.1.

If any of these variables are set to invalid values, or if any of the mandatory variables are undefined, the package manager’s behaviour is undefined; ideally, an error in one ebuild should not prevent operations upon other ebuilds or packages.

7.1 Metadata invariance

+ id="x1-670007.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 @@ -2617,7 +2647,7 @@ data.

7.2 Mandatory Ebuild-defined Variables

+ id="x1-680007.2">Mandatory Ebuild-defined Variables

All ebuilds must define at least the following variables:

A short human-readable description of the package’s pu SLOT

The package’s slot. Must be a valid slot name, as per section 3.1.3. May be defined +href="#x1-230003.1.3">3.1.3. May be defined by an eclass. Must not be empty.

In EAPIs shown in table 8.4 as supporting sub-slots, the 8.4 as supporting sub-slots, the SLOT variable may contain an optional sub-slot part that follows the regular slot and is delimited by a / character. The sub-slot must be a valid slot name, as per section 3.1.3. The sub-slot is used to +href="#x1-230003.1.3">3.1.3. The sub-slot is used to represent cases in which an upgrade to a new version of a package with a different sub-slot may require dependent packages to be rebuilt. When the sub-slot part is omitted from the SLOT definition, the package is considered to have an i

7.3 Optional Ebuild-defined Variables

+ id="x1-690007.3">Optional Ebuild-defined Variables

Ebuilds may define any of the following variables: @@ -2658,7 +2688,7 @@ class="description">The EAPI. See below. class="ecbx-1000">HOMEPAGE

The URI or URIs for a package’s homepage, including protocols. See section 8 for full syntax. +href="#x1-760008">8 for full syntax.

SRC_URI

https://, ftp:// and mirror:// (see section 4.4.2 for mirror behaviour). Fetch restricted +href="#x1-390004.4.2">4.4.2 for mirror behaviour). Fetch restricted packages may include URL parts consisting of just a filename. See section 8 for full +href="#x1-760008">8 for full syntax.

LICENSE

The package’s license. Each text token must correspond to a tree “licenses/” - entry (see section 4.5). See section 8 for full syntax. +class="description">The package’s license. Each text token must be a valid license name, as per + section 3.1.6, and must correspond to a tree “licenses/” entry (see section 4.5). See + section 8 for full syntax.

KEYWORDS

A whitespace separated list of keywords for the ebuild. Each token must be a valid keyword name, as per section 3.1.6. See section 7.3.2 for full syntax. +href="#x1-280003.1.7">3.1.7. See section 7.3.2 for full syntax.

IUSE

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 11.1.1 for discussion on which values must be - listed this variable. -

IUSE-DEFAULTS In EAPIs shown in table 7.1 as supporting 11.1.1 for discussion on which values must be + listed in this variable. +

iuse-defaults In EAPIs shown in table 7.1 as supporting IUSE defaults, any use flag name in IUSE may be prefixed by at most one of a plus or a minus sign. If such a prefix @@ -2711,66 +2742,65 @@ class="ectt-1000">IUSE may be prefixed by at most one of a plus or a minu REQUIRED_USE

REQUIRED-USE Zero or more assertions that must be met by the +class="eccc1000-">required-use Zero or more assertions that must be met by the configuration of USE flags to be valid for this ebuild. See section 8.2.7 for description +href="#x1-910008.2.7">8.2.7 for description and section 8 for full syntax. Only in EAPIs listed in table 7.2 as supporting +href="#x1-760008">8 for full syntax. Only in EAPIs listed in table 7.2 as supporting REQUIRED_USE.

PROPERTIES

PROPERTIES Zero or more properties for this package. See section 8.2.9 +class="eccc1000-">properties Zero or more properties for this package. See section 8.2.9 for value meanings and section 8 for full syntax. For EAPIs listed in table 7.2 as +href="#x1-760008">8 for full syntax. For EAPIs listed in table 7.2 as having optional support, ebuilds must not rely upon the package manager recognising or understanding this variable in any way.

RESTRICT

Zero or more behaviour restrictions for this package. See section 8.2.8 for +href="#x1-920008.2.8">8.2.8 for value meanings and section 8 for full syntax. +href="#x1-760008">8 for full syntax.

DEPEND

See section 8. +href="#x1-760008">8.

RDEPEND

See section 8. For some EAPIs, 8. For some EAPIs, RDEPEND has special behaviour for its value if unset and when used with an eclass. See section 7.3.3 for details. +href="#x1-720007.3.3">7.3.3 for details.

PDEPEND

See section 8.

+href="#x1-760008">8.

Table 7.1: EAPIs supporting IUSE defaults

+class="ectt-1000">IUSE defaults

Table 7.2: EAPIs supporting various ebuild-defined variables

+class="content">EAPIs supporting various ebuild-defined variables

7.3.1 EAPI

+ id="x1-700007.3.1">EAPI

An empty or unset EAPI value is equivalent to 0. Ebuilds must not assume that they will get a @@ -2887,19 +2917,19 @@ different.

7.3.2 Keywords

+ id="x1-710007.3.2">Keywords

Keywords are used to indicate levels of stability of a package on a respective architecture arch. -The following conventions are used:

- arch: Both the package version and the ebuild are widely tested, known to work and not have any serious issues on the indicated platform. This is referred to as a stable keyword.
- ~arch: The package version and the ebuild are believed to work and do not have any known serious bugs, but more testing is required before the package version is considered suitable for obtaining a stable keyword. This is referred to as an unstable class="ecti-1000">keyword or a testing keyword.
- No keyword: It is not known whether the package will work, or insufficient testing has +
- No keyword: It is not known whether the package will work, or insufficient testing has occurred.
- -arch: The package version will not work on the architecture.
The -* keyword is used to indicate package versions which are not worth trying to test on unlisted @@ -2921,13 +2951,11 @@ class="ectt-1000">KEYWORDS variable indicates uncertain functionality on

7.3.3 RDEPEND value
+ id="x1-720007.3.3">RDEPEND value
RDEPEND-DEPEND In EAPIs listed in table 7.3 as having rdepend-depend In EAPIs listed in table 7.3 as having RDEPEND=DEPEND, if RDEPEND is unset (but not if it is set to an empty string) in an ebuild, when generating metadata the package @@ -2940,23 +2968,23 @@ class="ectt-1000">RDEPEND set in an eclass does not change the implicit < class="ectt-1000">RDEPEND=DEPEND for the ebuild portion, and any DEPEND value set in an eclass does not get treated as being part of - - RDEPEND.
+ +

Table 7.3: EAPIs with RDEPEND=DEPEND Default
+class="ectt-1000">RDEPEND=DEPEND default

7.4 Magic Ebuild-defined Variables
+ id="x1-730007.4">Magic Ebuild-defined Variables
The following variables must be defined by inherit (see section 10.1), and may be considered to +href="#x1-11600010.1">10.1), and may be considered to be part of the ebuild’s metadata:
INHERITED
List of inherited eclass names. Again, this is handled magically by inherit.

Note: Thus, by extension of section 7.1, 7.1, inherit may not be used conditionally, except upon constant conditions.
The following are special variables defined by the package manager for internal use and may or @@ -3015,37 +3043,36 @@ may not be exported to the ebuild environment: DEFINED_PHASES
DEFINED-PHASES A space separated arbitrarily ordered list of +class="eccc1000-">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 7.4 as +href="#x1-75001r4">7.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 7.1, phase functions must not be defined based upon any variant +href="#x1-670007.1">7.1, phase functions must not be defined based upon any variant condition.

Table 7.4: EAPIs supporting DEFINED_PHASES
+class="ectt-1000">DEFINED_PHASES

Chapter 8
Dependencies
+ id="x1-760008">Dependencies
8.1 Dependency Classes
+ id="x1-770008.1">Dependency Classes

Table 8.1: Dependency classes required to be satisfied for a particular phase function
+class="content">Dependency classes required to be satisfied for a particular phase function

RDEPEND). These must be installed and usable before the class="ectt-1000">PDEPEND). These must be installed at some point before the package manager finishes the batch of installs.
Table 8.1 lists dependencies which must be satisfied before a particular phase function is +href="#x1-77001r1">8.1 lists dependencies which must be satisfied before a particular phase function is executed.
In addition, SRC_URI, REQUIRED_USE use dependency-style specifications to specify their values.
8.2 Dependency Specification Format
+ id="x1-780008.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. @@ -3234,14 +3261,14 @@ class="ectt-1000">proto://host/path. Permitted in SRC_URI and HOMEPAGE. In EAPIs listed in table 8.2 as supporting 8.2 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 8.2.10. +href="#x1-940008.2.10">8.2.10.
A flat filename. Permitted in SRC_URI. @@ -3250,10 +3277,9 @@ class="ectt-1000">SRC_URI. class="ectt-1000">GPL-2). Permitted in LICENSE.
-
A use flag name, optionally preceded by an exclamation mark. Permitted in REQUIRED_ +
A use flag name, optionally preceded by an exclamation mark. Permitted in USE. +class="ectt-1000">REQUIRED_USE.
A simple string. Permitted in RESTRICT and (item whitespace)* ’)’. Permitted in REQUIRED_USE.
AT-MOST-ONE-OF An at-most-one-of group, which consists of the string at-most-one-of An at-most-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 @@ -3305,7 +3328,7 @@ class="ectt-1000">at-most-one-of ::= ’??’ whitespace ’( (item whitespace)* ’)’. Permitted in REQUIRED_USE in EAPIs listed in table 8.3 +href="#x1-78002r3">8.3 as supporting REQUIRED_USE ?? groups.
@@ -3323,14 +3346,14 @@ class="ectt-1000">(item whitespace)* ’)’. Permitted in all sp

Table 8.2: EAPIs supporting SRC_URI arrows
+class="ectt-1000">SRC_URI arrows

Table 8.3: EAPIs supporting REQUIRED_USE ?? groups
+class="ectt-1000">REQUIRED_USE ?? groups

8.2.1 All-of Dependency Specifications
+ id="x1-790008.2.1">All-of dependency specifications
In an all-of group, all of the child elements must be matched.

8.2.2 Use-conditional Dependency Specifications
+ id="x1-800008.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 11.1.1. +href="#x1-12100011.1.1">11.1.1.

8.2.3 Any-of Dependency Specifications
+ id="x1-810008.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. @@ -3428,7 +3451,7 @@ matched.

8.2.4 Exactly-one-of Dependency Specifications
+ id="x1-820008.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. @@ -3437,7 +3460,7 @@ exactly-one-of group for match purposes.

8.2.5 At-most-one-of Dependency Specifications
+ id="x1-830008.2.5">At-most-one-of dependency specifications
Any use-conditional group that is an immediate child of an at-most-one-of group, if not enabled @@ -3448,7 +3471,7 @@ at-most-one-of group for match purposes.

8.2.6 Package Dependency Specifications
+ id="x1-840008.2.6">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.
@@ -3458,32 +3481,31 @@ class="ectt-1000">category/package name.
An operator, as described in section 8.2.6.1, followed immediately by 8.2.6.1, followed immediately by category/package, followed by a hyphen, followed by a version specification.

In EAPIs shown in table 8.4 as supporting 8.4 as supporting SLOT dependencies, either of the above formats may additionally be suffixed by a :slot restriction, as described in section 8.2.6.3. A package manager +href="#x1-880008.2.6.3">8.2.6.3. A package manager must warn or error if slot dependencies are used with an EAPI not supporting SLOT dependencies.

USE-DEPS In EAPIs shown in table 8.5 as supporting 2-style or 4-style use-deps In EAPIs shown in table 8.5 as supporting 2-style or 4-style USE dependencies, a specification may additionally be suffixed by at most one 2-style or 4-style [use] restriction, as described in section 8.2.6.4. A package manager must warn or error if this feature is used with an +href="#x1-890008.2.6.4">8.2.6.4. A package manager must warn or error if this feature is used with an EAPI not supporting use dependencies.

Note: Order is important. The slot restriction must come before use dependencies.

@@ -3491,14 +3513,14 @@ Order is important. The slot restriction must come before use dependencies.

Table 8.4: Support for SLOT dependencies and sub-slots in EAPIs

+class="ectt-1000">SLOT dependencies and sub-slots in EAPIs

Table 8.5: EAPIs supporting USE dependencies

+class="ectt-1000">USE dependencies

8.2.6.1 Operators

+ id="x1-860008.2.6.1">Operators

The following operators are available:

Strictly greater than the specified version.

8.2.6.2 Block Operator

+ id="x1-870008.2.6.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: @@ -3627,25 +3649,24 @@ the following exceptions:

Weak blocks on the package version of the ebuild itself do not count.

BANG-STRENGTH There are two strengths of block: weak and strong. A weak block may be ignored +class="eccc1000-">bang-strength There are two strengths of block: weak and strong. A weak block may be ignored by the package manager, so long as any blocked package will be uninstalled later on. A strong block must not be ignored. The mapping from one or two exclamation marks to strength is described in table 8.6. +href="#x1-87001r6">8.6.

Table 8.6: Exclamation mark strengths for EAPIs

+class="content">Exclamation mark strengths for EAPIs

8.2.6.3 Slot Dependencies

+ id="x1-880008.2.6.3">Slot dependencies

SLOT-DEPS A named slot dependency consists of a colon followed by a slot name. A specification +class="eccc1000-">slot-deps A named slot dependency consists of a colon followed by a slot name. A specification with a named slot dependency matches only if the slot of the matched package is equal to the slot specified. If the slot of the package to match cannot be determined (e. g. because it is not a supported EAPI), the match is treated as unsuccessful.

SUB-SLOT In EAPIs shown in table 8.4 as supporting sub-slots, a slot dependency may +class="eccc1000-">sub-slot In EAPIs shown in table 8.4 as supporting sub-slots, a slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a / character.

SLOT-OPERATOR-DEPS An operator slot dependency consists of a colon followed by one of the +class="eccc1000-">slot-operator-deps An operator slot dependency consists of a colon followed by one of the following operators:

Indicates that any slot value is acceptable. In addition, fo class="ecbx-1000">=

Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package will break unless a matching package with slot and sub-slot equal to - the slot and sub-slot of the best installed version at the time the package was installed - is available. + the slot and sub-slot of the best installed version at the time the package was built is + available.

slot=

Whenever the equals slot operator is used in an enabled dependency group, the dependencies +(DEPEND) must ensure that a matching package is installed at build time. It is invalid to use the +equals slot operator inside PDEPEND or inside any-of dependency specifications. +

8.2.6.4 2-Style and 4-Style Use Dependencies

A 2-style or 4-style use dependency consists of one of the following: + id="x1-890008.2.6.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 use flag is disab [-opt]; The flag must be disabled.

Multiple requirements may be combined using commas, e. g.

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 +

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

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 +

It is an error for an ebuild to use a conditional use dependency when that ebuild does not have the flag in IUSE_EFFECTIVE. -

8.2.7 Use State Constraints

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

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

It is an error for a flag to be used if it is not included in IUSE_EFFECTIVE. -

+ + +

8.2.8 Restrict

The following tokens are permitted inside Restrict +

The following tokens are permitted inside RESTRICT: - -

mirror: The package manager may not drop root privileges when buildi class="ecbx-1000">test; The src_test phase must not be run.

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

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

8.2.9 Properties

The following tokens are permitted inside 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. -

Ebuilds may not rely upon any token being supported. +

8.2.10 SRC_URI

All filename components that are enabled (i. e. not inside a use-conditional block that is not + id="x1-940008.2.10">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 +

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

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 +href="#x1-390004.4.2">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

The RESTRICT metadata key can be used to impose additional restrictions upon downloading—see section 8.2.8 for details. -

SRC-URI-ARROWS In EAPIs supporting arrows, if an arrow is used, the filename used when +href="#x1-920008.2.8">8.2.8 for details. + + +

src-uri-arrows In EAPIs supporting arrows, if an arrow is used, the filename used when saving to DISTDIR shall instead be the name on the right of the arrow. When consulting mirrors (except for those explicitly listed on the left of the arrow, if

Chapter 9
Ebuild-defined Functions

+ id="x1-950009">Ebuild-defined Functions

9.1 List of Functions

The following is a list of functions that an ebuild, or eclass, may define, and which will be called by + id="x1-960009.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 11.1), and the temporary directory +href="#x1-120001r1">11.1), and the temporary directory T; exceptions are noted below. All functions may assume that they have read access to all system libraries, binaries and configuration files that are accessible to normal users. -

The environment for functions run outside of the build sequence (that is,

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

Ebuilds must not call nor assume the existence of any phase functions. +

9.1.1 Initial Working Directories

Some functions may assume that their initial working directory is set to a particular location; these + id="x1-970009.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-workdir-fallback Some functions are described as having an initial working directory of S with an error or fallback to WORKDIR. For EAPIs listed in table 9.1 as having the +href="#x1-97001r1">9.1 as having the fallback, this means that if S is not a directory before the start of the phase function, the initial working directory shall be S is not a directory before the start of the phase func unless all of the following conditions are true, in which case the fallback to WORKDIR is used: -

The A variable contains no items. @@ -3967,8 +3985,8 @@ class="ectt-1000">DEFINED_PHASES.

@@ -3976,7 +3994,7 @@ class="ectt-1000">DEFINED_PHASES. >Table 9.1: EAPIs with S to WORKDIR fallbacks

+class="ectt-1000">WORKDIR fallbacks

9.1.2 pkg_pretend

PKG-PRETEND The pkg_pretend +

pkg-pretend The pkg_pretend function is only called for EAPIs listed in table 9.2 as supporting +href="#x1-98001r2">9.2 as supporting it. -

The

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 9.2: EAPIs supporting pkg_pretend

+class="ectt-1000">pkg_pretend

9.1.3 pkg_setup

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

9.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 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: -

Listing 9.1: src_unpack

+class="content">src_unpack

@@ -4116,43 +4130,42 @@ src_unpack() {
unpack ${A}
fi
}

9.1.5 src_prepare

SRC-PREPARE The src_prepare +

src-prepare The src_prepare function is only called for EAPIs listed in table 9.3 as supporting +href="#x1-101002r3">9.3 as supporting it. The src_prepare function can be used for post-unpack source preparation. -

The initial working directory is

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

SRC-PREPARE-6 For EAPIs listed in table 9.3 as using format 6, the default implementation used +href="#x1-970009.1.1">9.1.1. +

src-prepare-6 For EAPIs listed in table 9.3 as using format 6, the default implementation used when the ebuild lacks the src_prepare function shall behave as: -

Listing 9.2: src_prepare, format 6

+class="content">src_prepare, format 6

@@ -4164,12 +4177,12 @@ src_prepare() {
fi
eapply_user
}

For other EAPIs supporting

For other EAPIs supporting src_prepare, the default implementation used when the ebuild lacks the src_prepare function is a no-op. @@ -4177,15 +4190,15 @@ class="ectt-1000">src_prepare function is a no-op.

Table 9.3: src_prepare support and behaviour for EAPIs

+class="ectt-1000">src_prepare support and behaviour for EAPIs

9.1.6 src_configure

SRC-CONFIGURE The src_configure +

src-configure The src_configure function is only called for EAPIs listed in table 9.4 as +href="#x1-102002r4">9.4 as supporting it. -

The initial working directory is

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

The 9.1.1. +

The src_configure function configures the package’s build environment. The default implementation used when the ebuild lacks the src_configure function shall behave as: -

Listing 9.3: src_configure

+class="content">src_configure

@@ -4261,7 +4274,7 @@ src_configure() {
econf
fi
}

@@ -4269,15 +4282,15 @@ src_configure() {

Table 9.4: EAPIs supporting src_configure

+class="ectt-1000">src_configure

9.1.7 src_compile

SRC-COMPILE The 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

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

SRC-COMPILE-0 For EAPIs listed in table 9.5 as using format 0, the default implementation used +href="#x1-970009.1.1">9.1.1. +

src-compile-0 For EAPIs listed in table 9.5 as using format 0, the default implementation used when the ebuild lacks the src_compile function shall behave as: -

Listing 9.4: src_compile, format 0

+class="content">src_compile, format 0

@@ -4349,28 +4361,28 @@ src_compile() {
emake || die "emake failed"
fi
}

SRC-COMPILE-1 For EAPIs listed in table 9.5 as using format 1, the default implementation used +

src-compile-1 For EAPIs listed in table 9.5 as using format 1, the default implementation used when the ebuild lacks the src_compile function shall behave as: -

Listing 9.5: src_compile, format 1

+class="content">src_compile, format 1

@@ -4382,28 +4394,28 @@ src_compile() {
emake || die "emake failed"
fi
}

SRC-COMPILE-2 For EAPIs listed in table 9.5 as using format 2, the default implementation used +

src-compile-2 For EAPIs listed in table 9.5 as using format 2, the default implementation used when the ebuild lacks the src_compile function shall behave as: -

Listing 9.6: src_compile, format 2

+class="content">src_compile, format 2

@@ -4412,7 +4424,7 @@ src_compile() {
emake || die "emake failed"
fi
}

@@ -4420,15 +4432,15 @@ src_compile() {

Table 9.5: src_compile behaviour for EAPIs

+class="ectt-1000">src_compile behaviour for EAPIs

9.1.8 src_test

The 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

The initial working directory must be S if that exists, falling back to WORKDIR otherwise. The default implementation used when the ebuild lacks the emake test if and only if such a target is available. In both cases, if emake returns non-zero the build must be aborted. -

PARALLEL-TESTS For EAPIs listed in table 9.6 as not supporting parallel tests, the

parallel-tests For EAPIs listed in table 9.6 as not supporting parallel tests, the emake command must be called with option -j1. -

The

The src_test function may be disabled by RESTRICT. See section 8.2.8. It may be disabled by +href="#x1-920008.2.8">8.2.8. It may be disabled by user too, using a PM-specific mechanism.

Table 9.6: src_test behaviour for EAPIs

+class="ectt-1000">src_test behaviour for EAPIs

9.1.9 src_install

SRC-INSTALL The src_install +

src-install The src_install function installs the package’s content to a directory specified in D. -

The initial working directory is

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

SRC-INSTALL-4 For EAPIs listed in table 9.7 as using format 4, the default implementation used +href="#x1-970009.1.1">9.1.1. +

src-install-4 For EAPIs listed in table 9.7 as using format 4, the default implementation used when the ebuild lacks the src_install function shall behave as: -

Listing 9.7: src_install, format 4

+class="content">src_install, format 4

@@ -4580,28 +4590,28 @@ src_install() {
dodoc ${DOCS}
fi
}

SRC-INSTALL-6 For EAPIs listed in table 9.7 as using format 6, the default implementation used +

src-install-6 For EAPIs listed in table 9.7 as using format 6, the default implementation used when the ebuild lacks the src_install function shall behave as: -

Listing 9.8: src_install, format 6

+class="content">src_install, format 6

@@ -4611,27 +4621,27 @@ src_install() {
fi
einstalldocs
}

For other EAPIs, the default implementation used when the ebuild lacks the

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

Table 9.7: src_install behaviour for EAPIs

+class="ectt-1000">src_install behaviour for EAPIs

9.1.10 pkg_preinst

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

9.1.11 pkg_postinst

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

9.1.12 pkg_prerm

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

9.1.13 pkg_postrm

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

9.1.14 pkg_config

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

9.1.15 pkg_info

PKG-INFO The 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 9.8 as supporting 9.8 as supporting pkg_info on non-installed packages, it may also be called by the package manager when displaying information about a non-installed package. In this case, ebuild authors should note that dependencies may not be installed. -

pkg_info must not write to the filesystem.

Table 9.8: EAPIs supporting pkg_info on non-installed packages

+class="ectt-1000">pkg_info on non-installed packages

9.1.16 pkg_nofetch

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

9.1.17 default_ Phase Functions

DEFAULT-PHASE-FUNCS In EAPIs listed in table 9.9 as supporting Default phase functions +

default-phase-funcs In EAPIs listed in table 9.9 as supporting default_ phase functions, a function named default_(phase) that behaves as the default implementation for that EAPI shall @@ -4816,15 +4822,15 @@ functions except when in the phase in question.

Table 9.9: EAPIs supporting default_ phase functions

+class="ectt-1000">default_ phase functions

functions in phases +class="td11">

None

0, 1

None

2, 3

pkg_nofetch, src_unpack, @@ -4860,7 +4866,7 @@ class="ectt-1000">src_test

4, 5, 6

pkg_nofetch, src_unpack, @@ -4883,13 +4889,13 @@ class="td11">

9.2 Call Order

The call order for installing a package is: -

+ id="x1-1140009.2">Call Order +

The call order for installing a package is: +

pkg_pretend (only for EAPIs listed in table 9.2), which is called outside of the normal +href="#x1-98001r2">9.2), which is called outside of the normal call order process.
src_unpack
src_prepare (only for EAPIs listed in table 9.3) +href="#x1-101002r3">9.3)
src_configure (only for EAPIs listed in table 9.4) +href="#x1-102002r4">9.4)
src_compile @@ -4921,20 +4927,20 @@ class="ectt-1000">pkg_preinst
pkg_postinst

The call order for uninstalling a package is: -

The call order for uninstalling a package is: +

pkg_prerm
pkg_postrm

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

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

pkg_pretend (only for EAPIs listed in table 9.2), which is called outside of the normal +href="#x1-98001r2">9.2), which is called outside of the normal call order process.
src_unpack
src_prepare (only for EAPIs listed in table 9.3) +href="#x1-101002r3">9.3)
src_configure (only for EAPIs listed in table 9.4) +href="#x1-102002r4">9.4)
src_compile @@ -4974,23 +4980,23 @@ class="ectt-1000">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 +

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

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

For installing binary packages, the src phases are not called. -

When building binary packages that are not to be installed locally, the

When building binary packages that are not to be installed locally, the pkg_preinst and pkg_postinst functions are not called. @@ -5002,7 +5008,7 @@ class="ectt-1000">pkg_postinst functions are not called.

Chapter 10
Eclasses

+ id="x1-11500010">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 @@ -5010,7 +5016,7 @@ ebuild using them. The interpreter is therefore the same, and the same requireme parseable hold.

Eclasses must be located in the eclass directory in the top level of the repository—see section 4.6. +href="#x1-430004.6">4.6. Each eclass is a single file named <name>.eclass, where <name> is the name of this eclass, used by @@ -5019,7 +5025,7 @@ class="ectt-1000">inherit and EXPORT_FUNCTIONS among other places.

10.1 The inherit command

+ id="x1-11600010.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 @@ -5044,7 +5050,7 @@ class="ectt-1000">INHERITED metadata variable contains the name

10.2 Eclass-defined Metadata Keys

+ id="x1-11700010.2">Eclass-defined Metadata Keys

The IUSE, REQUIRED_USE, RDEPEND, this is done after the implicit RDEPEND rules in section 7.3.3 are applied. +href="#x1-720007.3.3">7.3.3 are applied.

10.3 EXPORT_FUNCTIONS

+ id="x1-11800010.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 @@ -5070,18 +5076,20 @@ eclass-defined version from it. The use of it is best illustrated by an example; listing 10.1 and is a snippet from a hypothetical 10.1 and is a snippet from a hypothetical foo.eclass.

Listing 10.1: EXPORT_FUNCTIONS example: foo.eclass

+class="content">EXPORT_FUNCTIONS example: foo.eclass

@@ -5123,16 +5131,16 @@ eclass.

Chapter 11
The Ebuild Environment

+ id="x1-11900011">The Ebuild Environment

11.1 Defined Variables

+ id="x1-12000011.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 11.2). For example, +href="#x1-12400011.2">11.2). For example, EBUILD_PHASE is different for every phase, and ROOT may have changed between the various @@ -5142,7 +5150,7 @@ variable. + id="x1-120001r1">

style="vertical-align:baseline;" id="TBL-24-1-"> +

Package name, version, and revision (if any), for example vim-7.0.174-r1.

Package name, for example vim.

The package’s category, for example app-editors.

Package version, with no revision. For example 7.0.174.

Package revision, or r0 if none exists.

Package version and revision (if any), for example 7.0.174 or 7.0.174-r1.

@@ -5299,55 +5308,87 @@ class="td11"> FILESDIR +class="ectt-1000">src_*, + global scope⁴

The full path to the directory in which the files in the A variable are stored.

The full path to the ebuild’s working directory, where all build data should be + contained.

The full path to the temporary build directory, used by src_compile, + src_install etc. Defaults to ${WORKDIR}/${P}. May be modified by ebuilds. If + S is assigned in the global scope of an ebuild, then the restrictions of section 11.2 + for global variables apply.

+ + - + + + + - - - - + - - + + + + - - - - - - +class="ectt-1000">pkg_info, pkg_pretend according to the top level ebuild function that was + executed by the package manager. May be unset or any single word that is not any + of the above when the ebuild is being sourced for other (e. g. metadata or QA) + purposes. Only for EAPIs listed in table 11.2 as supporting EBUILD_PHASE_FUNC.

A list of all versions of this package (including revision, if specified), whitespace + separated with no leading or trailing whitespace, that are being replaced + (uninstalled or overwritten) as a result of this install. See section 11.1.2. Only + for EAPIs listed in table 11.2 as supporting REPLACING_VERSIONS.

@@ -5673,17 +5679,17 @@ class="ectt-1000">REPLACING_VERSIONS. class="td11"> REPLACED_BY_VERSION

Table 11.2: EAPIs supporting various added env variables

+class="content">EAPIs supporting various added env variables

Table 11.1: Defined variables

+class="content">Defined variables

@@ -5188,78 +5196,80 @@ class="td11">

All

No²

Package name and version, without the revision part. For example, vim-7.0.174.

All

Ditto

Package name, for example vim.

11.1.1 USE and IUSE Handling

This section discusses the handling of four variables: + id="x1-12100011.1.1">USE and IUSE handling +

This section discusses the handling of four variables:

IUSE: IUSE_REFERENCEABLE may legally be used in queries
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). +class="description">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

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

For EAPIs listed in table 5.2 as not supporting profile defined

For EAPIs listed in table 5.2 as not supporting profile defined IUSE injection, IUSE_REFERENCEABLE is equal to the calculated IUSE injection is supported, IUSE_REFERENCEABLE is equal to IUSE_EFFECTIVE. -

For EAPIs listed in table 5.2 as not supporting profile defined

For EAPIs listed in table 5.2 as not supporting profile defined IUSE injection, IUSE_EFFECTIVE contains the following values: -

All values in the calculated IUSE value. @@ -6004,16 +6008,14 @@ class="ectt-1000">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.

PROFILE-IUSE-INJECT For EAPIs listed in table 5.2 as supporting profile defined

profile-iuse-inject For EAPIs listed in table 5.2 as supporting profile defined IUSE injection, IUSE_EFFECTIVE contains the following values: -

All values in the calculated IUSE value. @@ -6023,12 +6025,11 @@ class="ectt-1000">IUSE_IMPLICIT variable.
All values in the profile variable named USE_EXPAND_VALUES_${v}, where ${v} is - any value in the intersection of the profile USE_EXPAND_UNPREFIXED and USE_EXPAND_ +class="ectt-1000">${v} + is any value in the intersection of the profile USE_EXPAND_UNPREFIXED and IMPLICIT variables. +class="ectt-1000">USE_EXPAND_IMPLICIT variables.

${lower_v}

${v}

The

The USE variable is set by the package manager. For each value in IUSE_EFFECTIVE, USE shall contain that value if the flag is to be enabled for the ebuild in question, and shall not contain that value if it is to be disabled. In EAPIs listed in table 5.2 as not supporting profile +href="#x1-62001r2">5.2 as not supporting profile defined IUSE injection, USE may contain other flag names that are not relevant for the ebuild. -

For EAPIs listed in table 5.2 as supporting profile defined

For EAPIs listed in table 5.2 as supporting profile defined IUSE injection, the variables named in USE_EXPAND and USE_EXPAND_UNPREFIXED shall have their profile-provided values reduced to contain only those values that are present in IUSE_EFFECTIVE. -

For EAPIs listed in table 5.2 as supporting profile defined

For EAPIs listed in table 5.2 as supporting profile defined IUSE injection, the package manager must save the calculated value of IUSE_EFFECTIVE when installing a package. Details are beyond the scope of this specification. -

11.1.2 REPLACING_VERSIONS and REPLACED_BY_VERSION

REPLACE-VERSION-VARS In EAPIs listed in table 11.2 as supporting it, the REPLACING_VERSIONS and REPLACED_BY_VERSION +

replace-version-vars In EAPIs listed in table 11.2 as supporting it, the REPLACING_VERSIONS variable shall be defined in pkg_preinst and may be defined in class="ectt-1000">pkg_pretend and pkg_setup, although ebuild authors should take care to handle binary package creation and installation correctly when using it in these phases. -

REPLACING_VERSIONS is a list, not a single optional value, to handle pathological cases such as installing foo-2:2 to replace foo-2:1 and foo-3:2. -

In EAPIs listed in table 11.2 as supporting it, the

In EAPIs listed in table 11.2 as supporting it, the REPLACED_BY_VERSION variable shall be defined in pkg_prerm and pkg_postrm. It shall contain at most one value. -

11.1.3 Offset-prefix variables EPREFIX, EROOT and ED

+ id="x1-12300011.1.3">Offset-prefix variables

Table 11.6: EAPIs supporting offset-prefix

+class="content">EAPIs supporting offset-prefix

OFFSET-PREFIX-VARS Table 11.6 lists the EAPIs which support offset-prefix installations. This +

offset-prefix-vars Table 11.6 lists the EAPIs which support offset-prefix installations. This support was initially added in EAPI 3, in the form of three extra variables. Two of these, EROOT and EROOT properly set, though.

11.2 The state of variables between functions

+ id="x1-12400011.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

Variables with special meanings to the package manager are excluded from this rule.

Global variables must only contain invariant values (see 7.1). If a global variable’s value is +href="#x1-670007.1">7.1). If a global variable’s value is invariant, it may have the value that would be generated at any given point in the build sequence.

This is demonstrated by code listing 11.1. +href="#x1-125001r1">11.1.

Listing 11.1: Environment state between functions

+class="content">Environment state between functions

@@ -6238,20 +6230,20 @@ GLOBAL_VARIABLE="a"

11.3 Available commands

This section documents the commands available to an ebuild. Unless otherwise specified, they may + id="x1-12600011.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 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. -

11.3.1 System commands

Any ebuild not listed in the system set for the active profile(s) may assume the presence of every + id="x1-12700011.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 @@ -6260,15 +6252,15 @@ class="ectt-1000">base profile or equivalent, which is inherited by all a 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. -

11.3.1.1 Guaranteed system commands

The following commands must always be available in the ebuild environment: + id="x1-12800011.3.1.1">Guaranteed system commands +

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

All builtin commands in GNU bash, version as listed in table 6.1 on page 77. +href="#x1-64001r1">6.1 on page 80.
sed must be available, and must support all forms of invocations valid for GNU sed @@ -6278,22 +6270,21 @@ class="ectt-1000">sed must be available, and must support all forms of in class="ectt-1000">patch must be available, and must support all inputs valid for GNU patch.
GNU-FIND gnu-find find and xargs must be available, and must support all forms of invocations valid for GNU findutils version 4.4 or later. Only for EAPIs listed in table 11.7 as +href="#x1-129001r7">11.7 as requiring GNU find.

11.3.1.2 Shell options

FAILGLOB For EAPIs listed such in table 11.7, the Shell options +

failglob For EAPIs listed such in table 11.7, the failglob option of bash is set in the global scope of ebuilds. If set, failed pattern matches during filename expansion result in an error when the ebuild is being sourced. @@ -6303,14 +6294,14 @@ the ebuild is being sourced.

Table 11.7: System commands for EAPIs

+class="content">System commands for EAPIs

11.3.2 Commands provided by package dependencies

In some cases a package’s build process will require the availability of executables not provided by + id="x1-13000011.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. The availability of commands provided by the particular types of dependencies is explained in section 8.1. -

+href="#x1-770008.1">8.1. +

11.3.3 Ebuild-specific Commands

+ id="x1-13100011.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

11.3.3.1 Failure behaviour and related commands

+ id="x1-13200011.3.3.1">Failure behaviour and related commands

DIE-ON-FAILURE Where a command is listed as having EAPI dependent failure behaviour, a failure +class="eccc1000-">die-on-failure Where a command is listed as having EAPI dependent failure behaviour, a failure shall either result in a non-zero exit status or abort the build process, as determined by table 11.8. +href="#x1-132001r8">11.8.

The following commands affect this behaviour:

nonfatal: NONFATAL Executes the remainder of its arguments as a command, preserving the +class="eccc1000-">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, instead a non-zero exit status shall be returned. Only in EAPIs listed in table 11.8 as supporting 11.8 as supporting nonfatal.
Explicit die or assert commands only respect nonfatal when called with the -n option and in EAPIs supporting this option, see table 11.10.

+href="#x1-137001r11">11.11.

Table 11.8: EAPI Command Failure Behaviour

+class="content">EAPI command failure behaviour

11.3.3.2 Banned commands

+ id="x1-13300011.3.3.2">Banned commands

BANNED-COMMANDS Some commands are banned in some EAPIs. If a banned command is called, +class="eccc1000-">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 11.9: Banned commands

+class="content">Banned commands

11.3.3.3 Sandbox commands

+ id="x1-13400011.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. @@ -6533,16 +6521,14 @@ class="description">Add a directory to the deny list.

11.3.3.4 Package manager query commands

+ id="x1-13500011.3.3.4">Package manager query commands

These commands are used to extract information about the system. Ebuilds must not run any of these commands in parallel with any other package manager command. Ebuilds must not run any of these commands once the current phase function has returned.

HOST-ROOT-OPTION In EAPIs listed in table 11.18 as supporting option host-root-option In EAPIs listed in table 11.10 as supporting option --host-root, this flag as the first argument will cause the query to apply to the host root instead of Takes exactly one package dependency specification as a matching package is installed, prints the category, package name and version of the highest matching version; otherwise, prints an empty string. The exit code is unspecified. -

11.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. -
+ + + + Table 11.10: EAPIs supporting --host-root for *_version commands + + + + + EAPI *_version supports --host-root? + 0, 1, 2, 3, 4 No 5, 6 Yes + + + +

11.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. @@ -6614,26 +6639,25 @@ class="ectt-1000">ebegin message has completed. Takes subsequent arguments. If the first argument is 0, prints a success indicator; otherwise, prints the message followed by a failure indicator. Returns its first argument as exit status.

11.3.3.6 Error commands

These commands are used when an error is detected that will prevent the build process from + id="x1-13700011.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: NONFATAL-DIE If called under the nonfatal-die If called under the nonfatal command (as per section 11.3.3.1) and +href="#x1-13200011.3.3.1">11.3.3.1) and with -n as its first parameter, displays a failure message provided in its following argument and then returns a non-zero exit status. Only in EAPIs listed in table 11.10 +href="#x1-137001r11">11.11 as supporting option -n. Otherwise, displays a failure message provided in its first and only argument, and then aborts the build process. assert; Checks the value of the shell’s pipe status variable, and if any component is non-zero (indicating failure), calls die, passing any parameters to it.

+ +

Table 11.10: Table 11.11: EAPIs supporting -n for die and assert commands

+class="ectt-1000">assert commands


EAPI	EAPI	die and support -n?
0, 1, 2, 3, 4, 5		0, 1, 2, 3, 4, 5	No
6		6	Yes

11.3.3.7 Patch commands

These commands are used during the Patch commands +

These commands are used during the src_prepare phase to apply patches to the package’s sources. Ebuilds must not run any of these commands once the current phase function has returned. @@ -6701,267 +6727,241 @@ returned. eapply

EAPPLY Takes zero or more GNU patch options, followed by one or more file or +class="eccc1000-">eapply Takes zero or more GNU patch options, followed by one or more file or directory paths. Processes options and applies all patches found in specified locations according to Algorithm 11.1. If applying the patches fails, it aborts the build using +href="#x1-138001r1">11.1. If applying the patches fails, it aborts the build using die, unless run using nonfatal, in which case it returns non-zero exit status. Only available in EAPIs listed in table 11.11 as supporting 11.12 as supporting eapply. -

-eapply_user

EAPPLY-USER Takes no arguments. Package managers supporting it apply - user-provided patches to the source tree in the current working directory. Exact - behaviour is implementation defined and beyond the scope of this specification. Package - managers not supporting it must implement the command as a no-op. Returns shell - true (0) if patches applied successfully, or if no patches were provided. Otherwise, - aborts the build process, unless run using nonfatal, in which case it returns non-zero - exit status. Only available in EAPIs listed in table 11.11 as supporting eapply_user. - In EAPIs where it is supported, eapply_user must be called once in the src_prepare - phase. For any subsequent calls, the command will do nothing and return 0.

- - -

- -

Algorithm 11.1: eapply logic

+class="content">eapply logic

- 1: + 1: if any parameter is equal to "--" then -
2: collect all parameters before the first +
2: collect all parameters before the first "--" in the options array -
3: collect all parameters after the first +
3: collect all parameters after the first "--" in the files array -
4: +
4: else if any parameter that begins with a hyphen follows one that does not then -
5: abort the build process with an error + id="x1-138006r119"> +
5: abort the build process with an error -
6: +
6: else -
7: collect all parameters beginning with a hyphen in the +
7: collect all parameters beginning with a hyphen in the options array -
8: collect all remaining parameters in the +
8: collect all remaining parameters in the files array -
9: +
9: end if -
10: +
10: if the files array is empty then -
11: abort the build process with an error + id="x1-138012r125"> +
11: abort the build process with an error -
12: +
12: end if -
13: +
13: for all x in the files array do -
14: +
14: if $x is a directory then -
15: +
15: if not any files match $x/*.diff or $x/*.patch then -
16: abort the build process with an error + id="x1-138017r130"> +
16: abort the build process with an error -
17: +
17: end if -
18: +
18: for all files f matching $x/*.diff or $x/*.patch, sorted in POSIX locale do -
19: call +
19: call patch -p1 -f -g0 --no-backup-if-mismatch "${options[@]}" < "$f" -
20: +
20: if child process returned with non-zero exit status then -
21: + + +
21: return immediately with that status -
22: +
22: end if -
23: +
23: end for -
24: +
24: else -
25: call +
25: call patch -p1 -f -g0 --no-backup-if-mismatch "${options[@]}" < "$x" -
26: +
26: if child process returned with non-zero exit status then -
27: +
27: return immediately with that status -
28: +
28: end if -
29: +
29: end if -
30: +
30: end for -
31: +
31: return shell true (0) -

- - -

+eapply_user

eapply-user Takes no arguments. Package managers supporting it apply + user-provided patches to the source tree in the current working directory. Exact + behaviour is implementation defined and beyond the scope of this specification. + Package managers not supporting it must implement the command as a no-op. + Returns shell true (0) if patches applied successfully, or if no patches were provided. + Otherwise, aborts the build process, unless run using nonfatal, in which case it returns + non-zero exit status. Only available in EAPIs listed in table 11.12 as supporting + eapply_user. In EAPIs where it is supported, eapply_user must be called once in the + src_prepare phase. For any subsequent calls, the command will do nothing and + return 0.

Table 11.11: Patch commands for EAPIs

+>Table 11.12: Patch commands for EAPIs


EAPI	EAPI	eapply?	?	eapply_user?
0, 1, 2, 3, 4, 5	No		0, 1, 2, 3, 4, 5	No	No
6	Yes		6	Yes	Yes

11.3.3.8 Build commands

These commands are used during the Build commands +

These commands are used during the src_configure, src_compile, and src_install phases to @@ -6979,13 +6979,12 @@ class="ectt-1000">./configure, after the default options below. 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

+ is set, in which case it is taken to be the directory containing it. +

econf-options econf must pass the following options to the configure script: +

--prefix must default to ${EPREFIX}/usr unless overridden by ${EPREFIX}/var/lib
--docdir must be ${EPREFIX}/usr/share/doc/${PF}, if the EAPI is listed in table 11.12 as using it. This option will only be passed if the string 11.13 as using it. This option will only be passed if the string --docdir occurs in the output of configure --help. @@ -7017,7 +7016,7 @@ class="ectt-1000">configure --help.
--htmldir must be ${EPREFIX}/usr/share/doc/${PF}/html, if the EAPI is listed in table 11.12 as using it. This option will only be passed if the string 11.13 as using it. This option will only be passed if the string --htmldir occurs in the output of configure --help. @@ -7026,17 +7025,17 @@ class="ectt-1000">configure --help. class="ectt-1000">CHOST environment variable.
--libdir must be set according to Algorithm 11.2. +href="#x1-139002r2">11.2.
--disable-dependency-tracking, if the EAPI is listed in table 11.12 as using it. +href="#x1-139001r13">11.13 as using it. This option will only be passed if the string --disable-dependency-tracking occurs in the output of configure --help.
--disable-silent-rules, if the EAPI is listed in table 11.12 as using it. This option +href="#x1-139001r13">11.13 as using it. This option will only be passed if the string --disable-silent-rules occurs in the output @@ -7044,75 +7043,75 @@ class="ectt-1000">--disable-silent-rules occurs in the output of configure --help.

Table 11.12: Table 11.13: Extra econf arguments for EAPIs

+class="ectt-1000">econf arguments for EAPIs


EAPI	EAPI	--disable-dependency-tracking	--disable-dependency-tracking	--disable-silent-rules	--disable-silent-rules	--docdir	--docdir	--htmldir
0, 1, 2, 3	No	No	No		0, 1, 2, 3	No	No	No	No
4	Yes	No	No		4	Yes	No	No	No
5	Yes	Yes	No		5	Yes	Yes	No	No
6	Yes	Yes	Yes		6	Yes	Yes	Yes	Yes

Note that the

Note that the ${EPREFIX} component represents the same offset-prefix as described in Table 11.1. It facilitates offset-prefix installations which is supported by EAPIs listed in +href="#x1-120001r1">11.1. It facilitates offset-prefix installations which is supported by EAPIs listed in Table 11.4. When no offset-prefix installation is in effect, 11.4. When no offset-prefix installation is in effect, EPREFIX becomes the empty string, making the behaviour of econf equal for both offset-prefix supporting and agnostic EAPIs. -

econf must be implemented internally—that is, as a bash function and not an external script. Should any portion of it fail, it must abort the build using die, unless run using @@ -7120,69 +7119,65 @@ class="ectt-1000">die, unless run using class="ectt-1000">nonfatal, in which case it must return non-zero exit status.

Algorithm 11.2: econf --libdir logic

+class="content">econf --libdir logic

- 1: let prefix=${EPREFIX}/usr -
2: + 1: let prefix=${EPREFIX}/usr +
2: if the caller specified --prefix=$p then -
3: let prefix=$p + id="x1-139005r148"> +
3: let prefix=$p -
4: +
4: end if -
5: let libdir= -
6: +
5: let libdir= +
6: if the ABI environment variable is set then -
7: let libvar=LIBDIR_$ABI -
8: +
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 + id="x1-139011r154"> +
9: let libdir=the value of the variable named by libvar -
10: +
10: end if -
11: +
11: end if -
12: +
12: if libdir is non-empty then -
13: pass --libdir=$prefix/$libdir to configure + id="x1-139015r158"> +
13: pass --libdir=$prefix/$libdir to configure -
14: +
14: end if

@@ -7197,50 +7192,51 @@ class="ectt-1000">MAKE variable is unset. Any arguments given class="ectt-1000">MAKEOPTS. Arguments given to emake override user configuration. See also section 11.3.1.1. 11.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 11.3.3.1. +href="#x1-13200011.3.3.1">11.3.3.1.

einstall

A shortcut for the command given in Listing 11.2. Any arguments given to 11.2. Any arguments given to einstall are passed verbatim to emake, as shown. Failure behaviour is EAPI dependent as per section 11.3.3.1. In EAPIs listed in table 11.9, this command is banned as per +href="#x1-13200011.3.3.1">11.3.3.1. In EAPIs listed in table 11.9, this command is banned as per section 11.3.3.2. -

The variable 11.3.3.2. +

The variable ED is defined as in Table 11.1 and depends on the use of an offset-prefix. +href="#x1-120001r1">11.1 and depends on the use of an offset-prefix. When such offset-prefix is absent, ED is equivalent to D. ED is always available in EAPIs that support offset-prefix installations as listed in Table 11.4, hence EAPIs +href="#x1-120009r4">11.4, hence EAPIs lacking offset-prefix support should use D instead of ED in the command given in Listing 11.2. Variable 11.2. Variable libdir is an auxiliary local variable whose value is determined by Algorithm 11.3. -

11.3. +

Listing 11.2: einstall command

+class="content">einstall command

@@ -7255,13 +7251,13 @@ emake \
   -j1 \
   "$@" \
   install

11.3.3.9 Installation commands

These commands are used to install files into the staging area, in cases where the package’s + id="x1-14000011.3.3.9">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 @@ -7288,34 +7284,34 @@ class="ectt-1000">0755 and transfers file ownership to the superuser or i class="ectt-1000">root:root, while on an offset-prefix aware installation this may be joe:users. Failure behaviour is EAPI dependent as per section 11.3.3.1. +href="#x1-13200011.3.3.1">11.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 11.3.3.1. +class="ectt-1000">0644, + or with the install options set by the most recent insopts call. Failure behaviour is + EAPI dependent as per section 11.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 11.3.3.1. +class="ectt-1000">0755, or with the install + options set by the most recent diropts call. Failure behaviour is EAPI dependent as + per section 11.3.3.1.

dodoc

DODOC Installs the given files into a subdirectory under 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 @@ -7324,13 +7320,13 @@ class="ectt-1000">docinto. If docinto has not yet been called, instead installs to the directory /usr/share/doc/${PF}/. For EAPIs listed in table 11.13 as supporting 11.14 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 11.3.3.1. +href="#x1-13200011.3.3.1">11.3.3.1.

@@ -7339,49 +7335,53 @@ class="ecbx-1000">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 +class="ectt-1000">0644, or with the install options set by the most recent insopts call. Failure behaviour is EAPI dependent as per section 11.3.3.1. +href="#x1-13200011.3.3.1">11.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 +class="ectt-1000">exeinto call. If exeopts function. If exeinto has not yet been called, behaviour is undefined. Failure - behaviour is EAPI dependent as per section 11.3.3.1. +class="ectt-1000">exeinto has not yet been called, behaviour is undefined. Files are installed by default + with file mode 0755, or with the install options set by the most recent exeopts call. + Failure behaviour is EAPI dependent as per section 11.3.3.1.

dohard

Takes two parameters. Creates a hardlink from the second to the first. In EAPIs - listed in table 11.9, this command is banned as per section 11.3.3.2. +class="description">Takes two parameters. Creates a hardlink from the second to the first. Both paths + 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. In EAPIs listed + in table 11.9, this command is banned as per section 11.3.3.2.

doheader

DOHEADER Installs the given header files into /usr/include/, by default with file - mode 0644. This can be overridden by setting INSOPTIONS with the insopts function. +class="eccc1000-">doheader Installs the given header files into /usr/include/, by default with + file mode 0644, or with the install options set by the most recent insopts call. If the first argument is -r, then operates recursively, descending into any directories given. Only available in EAPIs listed in table 11.14 as supporting 11.15 as supporting doheader. Failure behaviour is EAPI dependent as per section 11.3.3.1. +href="#x1-13200011.3.3.1">11.3.3.1.

dohtml

-r). class="description">-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 11.3.3.1. -

It is undefined whether a failure shall occur if

Failure behaviour is EAPI dependent as per section 11.3.3.1. +

It is undefined whether a failure shall occur if -r is not specified and a directory is encountered. Ebuilds must not rely upon any particular behaviour.

@@ -7446,161 +7446,153 @@ class="description">Installs the given GNU Info files into the /usr/share/info area with file mode 0644. Failure behaviour is EAPI dependent as per section 11.3.3.1. +href="#x1-13200011.3.3.1">11.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 11.3.3.1. +class="ectt-1000">0755, or + with the install options set by the most recent exeopts call. Failure behaviour is EAPI + dependent as per section 11.3.3.1.

doins

DOINS Takes one or more files as arguments and installs them into doins Takes one or more 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 11.15, 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 11.3.3.1. +class="ectt-1000">0644, or with the install options set by the most recent insopts call. If the + first argument is -r, then operates recursively, descending into any directories given. For + EAPIs listed in table 11.16, 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 11.3.3.1.

dolib

For each argument, installs it into the appropriate library subdirectory under DESTTREE, as determined by Algorithm 11.3. The file mode is 0644 by default. 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 11.3.3.1. +href="#x1-140001r3">11.3. Files are installed by default with file mode 0644, or with the + install options set by the most recent libopts call. Any symlinks are installed into the + same directory as relative links to their original target. Failure behaviour is EAPI dependent + as per section 11.3.3.1.

dolib.so

dolib.a

As for dolib except each file is installed with mode 0755. +class="ectt-1000">0644.

dolib.a

dolib.so

As for dolib except each file is installed with mode 0644. +class="ectt-1000">0755.

Algorithm 11.3: Determining the library directory

+class="content">Determining the library directory

- 1: + 1: if CONF_LIBDIR_OVERRIDE is set in the environment then -
2: return CONF_LIBDIR_OVERRIDE + id="x1-140003r161"> +
2: return CONF_LIBDIR_OVERRIDE -
3: +
3: end if -
4: +
4: if CONF_LIBDIR is set in the environment then -
5: let LIBDIR_default=CONF_LIBDIR + id="x1-140006r164"> +
5: let LIBDIR_default=CONF_LIBDIR -
6: +
6: else -
7: let LIBDIR_default=“lib” + id="x1-140008r166"> +
7: let LIBDIR_default=“lib” -
8: +
8: end if -
9: +
9: if ABI is set in the environment then -
10: let abi=ABI + id="x1-140011r169"> +
10: let abi=ABI -
11: +
11: else if DEFAULT_ABI is set in the environment then -
12: let abi=DEFAULT_ABI + id="x1-140013r171"> +
12: let abi=DEFAULT_ABI -
13: +
13: else -
14: let abi=“default” + id="x1-140015r173"> +
14: let abi=“default” -
15: +
15: end if -
16: return the value of LIBDIR_$abi + id="x1-140017r175"> +
16: return the value of LIBDIR_$abi

+ +

doman

Installs the given man pages 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 11.16 as supporting language detection by filename, a +

doman-langs In EAPIs listed in table 11.17 as supporting language detection by filename, a man page with name of the form foo.lang/man1/foo.1, class="ecti-1000">lang refers to a pair of lower-case ASCII letters optionally followed by an underscore and a pair of upper-case ASCII letters. Failure behaviour is EAPI dependent as per section 11.3.3.1. -

With option 11.3.3.1. +

With option -i18n=lang, a man page shall be installed into an appropriate subdirectory of foo.pl.1). The lang subdirectory level is skipped if lang is the empty string. In EAPIs specified by table 11.16, the 11.17, the -i18n option takes precedence over the language code in the filename.

@@ -7644,7 +7636,7 @@ class="ectt-1000">/LC_MESSAGES. The name of the installed files is the package name with .mo appended. Failure behaviour is EAPI dependent as per section 11.3.3.1. +href="#x1-13200011.3.3.1">11.3.3.1.

dosbin

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 11.3.3.1. +href="#x1-13200011.3.3.1">11.3.3.1.

fowners

Acts as for chown, but takes paths relative to the image directory. Failure behaviour is EAPI dependent as per section 11.3.3.1. +href="#x1-13200011.3.3.1">11.3.3.1.

fperms

Acts as for chmod, but takes paths relative to the image directory. Failure behaviour is EAPI dependent as per section 11.3.3.1. +href="#x1-13200011.3.3.1">11.3.3.1. +

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

newbin

NEWFOO-STDIN As for newfoo-stdin 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. In EAPIs specified by table 11.17, standard input is read when the first parameter is 11.18, standard input is read when the first parameter is - (a hyphen). In this case, it is an error if standard input is a terminal.

@@ -7706,6 +7707,8 @@ class="ectt-1000">doenvd. class="ecbx-1000">newexe

As above, for doexe. + +

newheader

doinitd. class="ecbx-1000">newins

As above, for doins. - -

newlib.a

doman. class="ecbx-1000">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 11.3.3.1.

Table 11.13: Table 11.14: EAPIs supporting dodoc -r

+class="ectt-1000">dodoc -r


EAPI	EAPI	Supports dodoc -r?
0, 1, 2, 3		0, 1, 2, 3	No
4, 5, 6		4, 5, 6	Yes

@@ -7798,25 +7789,25 @@ class="td11">

Table 11.14: Table 11.15: EAPIs supporting doheader and newheader

+class="ectt-1000">newheader


EAPI	EAPI	Supports doheader and newheader?
0, 1, 2, 3, 4		0, 1, 2, 3, 4	No
5, 6		5, 6	Yes

@@ -7842,38 +7833,38 @@ class="td11">

Table 11.15: Table 11.16: EAPIs supporting symlinks for doins

+class="ectt-1000">doins


EAPI	EAPI	doins supports symlinks?
0, 1, 2, 3		0, 1, 2, 3	No
4, 5, 6		4, 5, 6	Yes

@@ -7882,49 +7873,49 @@ class="td11">

Table 11.16: Table 11.17: doman language support options for EAPIs

+class="ectt-1000">doman language support options for EAPIs


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

@@ -7933,56 +7924,15 @@ class="td11">

- - -

Table 11.17: EAPIs supporting stdin for new* commands

- - - -

EAPI	new* can read from stdin? -
0, 1, 2, 3, 4	No
5, 6	Yes

- - -

Table 11.18: EAPIs supporting --host-root for *_version commands

+class="content">EAPIs supporting stdin for new* commands

EAPI

+class="td11"> No +class="td11"> Yes

_version supports --host-root? +class="ectt-1000">new can read from stdin?
0, 1, 2, 3, 4	No
5, 6	Yes

11.3.3.10 Commands affecting install destinations

The following commands are used to set the various destination trees, all relative to 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 @@ -8033,7 +7981,7 @@ class="ectt-1000">${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 11.3.3.1. +href="#x1-13200011.3.3.1">11.3.3.1.

insinto

Sets the options passed by dolib et al. to the install command.

11.3.3.11 Commands affecting install compression

DOCOMPRESS In EAPIs listed in table 11.19 as supporting controllable compression, the -package manager may optionally compress a subset of the files under the ED directory in -offset-prefix aware EAPIs or the D directory in offset-prefix agnostic EAPIs. To control which + id="x1-14200011.3.3.11">Commands affecting install compression +

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

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

The optional compression shall be carried out after

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: +class="ectt-1000">ED variable prepended, then:

If it is a directory, act as if every file or directory immediately under this directory @@ -8125,10 +8069,8 @@ EAPIs prepended, then:
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: -

+class="ectt-1000">ED variable prepended, then: +

If it is a directory, act as if every file or directory immediately under this directory were in the exclusion list. @@ -8136,10 +8078,10 @@ offset-prefix agnostic EAPIs prepended, then:
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 +

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

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.

@@ -8149,19 +8091,19 @@ class="description">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 11.19 as supporting 11.19 as supporting docompress.

Table 11.19: EAPIs supporting controllable compression

+class="content">EAPIs supporting controllable compression

11.3.3.12 Use List Functions

These functions provide behaviour based upon set or unset use flags. Ebuilds must not run any of + id="x1-14300011.3.3.12">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. It is an error if an ebuild calls any of these functions in global scope. -

Unless otherwise noted, if any of these functions is called with a flag value that is not +

Unless otherwise noted, if any of these functions is called with a flag value that is not included in IUSE_EFFECTIVE, either behaviour is undefined or it is an error as decided by table 11.20. +href="#x1-143001r20">11.20.

use: use. use_with; USE-WITH Has one-, two-, and three-argument forms. The first argument is a +class="eccc1000-">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 11.21 as not supporting it, an empty third argument is treated +href="#x1-143002r21">11.21 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 --without-. usex; USEX Accepts at least one and at most five arguments. The first argument is a USE +class="eccc1000-">usex Accepts at least one and at most five arguments. The first argument is a USE flag name, any subsequent arguments (${arg2} to ${arg5}) are string values. If not @@ -8276,32 +8217,32 @@ class="ectt-1000">${arg2}${arg4}. class="ectt-1000">${arg3}${arg5}. The condition is inverted if the flag name is prefixed with !. Only available in EAPIs listed in table 11.22 as supporting 11.22 as supporting usex.
in_iuse: IN-IUSE Returns shell true (0) if the first argument (a in-iuse Returns shell true (0) if the first argument (a USE flag name) is included in IUSE_EFFECTIVE, false otherwise. Only available in EAPIs listed in table 11.22 as +href="#x1-143003r22">11.22 as supporting in_iuse.

Table 11.20: EAPI Behaviour for Use Queries not in IUSE_EFFECTIVE

+class="content">EAPI behaviour for use queries not in IUSE_EFFECTIVE

@@ -8341,7 +8282,7 @@ class="td11">

>Table 11.21: EAPIs supporting empty third argument in use_with and use_enable

+class="ectt-1000">use_enable

@@ -8381,7 +8322,7 @@ class="td11">

>Table 11.22: EAPIs supporting usex and in_iuse

+class="ectt-1000">in_iuse

11.3.3.13 Text List Functions

These functions check whitespace-separated lists for a particular value. + id="x1-14400011.3.3.13">Text list functions +

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

has: has, but also prints the first argument if found. class="ecbx-1000">hasq; Deprecated synonym for has.

11.3.3.14 Misc Commands

The following commands are always available in the ebuild environment, but don’t really fit in any + id="x1-14500011.3.3.14">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.

@@ -8460,9 +8401,9 @@ class="ectt-1000">sed is run with the current expression on that class="ectt-1000">s:${ED}::g in offset-prefix aware EAPIs and s:${D}::g in offset-prefix agnostic EAPIs. In EAPIs listed in table 11.9, this command is banned +href="#x1-133001r9">11.9, this command is banned as per section 11.3.3.2. +href="#x1-13300011.3.3.2">11.3.3.2.

unpack

Unpacks one or more source archives, in order, into the curr class="ectt-1000">a+r,u+w,go-w and that all directories under the current working directory additionally have permissions a+x. -

Arguments to unpack are interpreted as follows:

A filename without path (i. e., not containing any slash) is looked up in
Arguments to unpack are interpreted as follows: +
- A filename without path (i. e., not containing any slash) is looked up in DISTDIR.
- An argument starting with the string An argument starting with the string ./ is a path relative to the working directory.
- UNPACK-ABSOLUTE Otherwise, for EAPIs listed in table 11.23 as supporting +
- unpack-absolute Otherwise, for EAPIs listed in table 11.23 as supporting absolute and relative paths, the argument is interpreted as a literal path (absolute, or relative to the working directory); for EAPIs listed as not supporting such paths, unpack shall abort the build process.
- - -
Any unrecognised file format shall be skipped silently. If unpacking a supported file format +
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 + + +
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. +class="ectt-1000">*.tar). Ebuilds must ensure that GNU tar is installed.
- gzip-compressed files (*.gz, *.Z). Ebuilds must ensure that GNU gzip is @@ -8544,46 +8483,44 @@ class="ectt-1000">*.deb). Ebuilds must ensure that the deb2targz program ensure that GNU binutils is installed.
- lzma-compressed files (*.lzma). Ebuilds must ensure that LZMA Utils is installed. +class="ectt-1000">*.lzma). Ebuilds must ensure that XZ Utils is installed.
- lzma-compressed tar files (*.tar.lzma). Ebuilds must ensure that LZMA Utils - and GNU tar are installed. +class="ectt-1000">*.tar.lzma). Ebuilds must ensure that XZ Utils and + GNU tar are installed.
- xz-compressed files (*.xz). Ebuilds must ensure that XZ Utils is installed. Only for EAPIs listed in table 11.24 as supporting 11.24 as supporting .xz.
- xz-compressed tar files (*.tar.xz, *.txz). Ebuilds must ensure that XZ Utils and GNU tar are installed. Only for EAPIs listed in table 11.24 as supporting +href="#x1-145002r24">11.24 as supporting .tar.xz or .txz.
-
It is up to the ebuild to ensure that the relevant external utilities are available, whether by +
It is up to the ebuild to ensure that the relevant external utilities are available, whether by being in the system set or via dependencies. - - -
UNPACK-IGNORE-CASE
unpack-ignore-case unpack matches filename extensions in a case-insensitive manner, for EAPIs listed such in table 11.23. +href="#x1-145001r23">11.23.
+ +
-

Table 11.23: unpack behaviour for EAPIs
+class="ectt-1000">unpack behaviour for EAPIs

Yes class="td11">

-

Table 11.24: unpack extensions for EAPIs
+class="ectt-1000">unpack extensions for EAPIs

inherit
See section 10.1. +href="#x1-11600010.1">10.1.
default
DEFAULT-FUNC Calls the default-func Calls the default_ function for the current phase (see section 9.1.17). +href="#x1-1130009.1.17">9.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 11.25 as supporting +href="#x1-145034r25">11.25 as supporting default.
einstalldocs
EINSTALLDOCS Takes no arguments. Installs the files specified by the einstalldocs Takes no arguments. Installs the files specified by the DOCS and HTML_DOCS variables or a default set of files, according to Algorithm 11.4. If called using +href="#x1-145003r4">11.4. If called using nonfatal and any of the called commands returns a non-zero exit status, returns immediately with the same exit status. Only available in EAPIs listed in table 11.25 as +href="#x1-145034r25">11.25 as supporting einstalldocs. -
-get_libdir
GET-LIBDIR Prints the libdir name obtained according to Algorithm 11.5. Only - available in EAPIs listed in table 11.25 as supporting get_libdir.

- - -

- -

Algorithm 11.4: einstalldocs logic

+class="content">einstalldocs logic

- 1: save the value of the install directory for + 1: save the value of the install directory for dodoc -
2: set the install directory for +
2: set the install directory for dodoc to /usr/share/doc/${PF} -
3: +
3: if the DOCS variable is a non-empty array then -
4: call +
4: call dodoc -r "${DOCS[@]}" -
5: +
5: else if the DOCS variable is a non-empty scalar then -
6: call +
6: call dodoc -r ${DOCS} -
7: +
7: else if the DOCS variable is unset then -
8: +
8: for all d matching the filename expansion of README* ChangeLog AUTHORS NEWS TODO @@ -8763,138 +8685,130 @@ class="ectt-1000">README* ChangeLog AUTHORS NEWS TODO class="ectt-1000">CHANGES THANKS BUGS FAQ CREDITS CHANGELOG do -
9: +
9: if file d exists and has a size greater than zero then -
10: call +
10: call dodoc with d as argument -
11: + + +
11: end if -
12: +
12: end for -
13: +
13: end if -
14: set the install directory for +
14: set the install directory for dodoc to /usr/share/doc/${PF}/html -
15: +
15: if the HTML_DOCS variable is a non-empty array then -
16: call +
16: call dodoc -r "${HTML_DOCS[@]}" -
17: +
17: else if the HTML_DOCS variable is a non-empty scalar then -
18: call +
18: call dodoc -r ${HTML_DOCS} -
19: +
19: end if -
20: restore the value of the install directory for +
20: restore the value of the install directory for dodoc -
21: +
21: return shell true (0) -

- - -

+get_libdir

get-libdir Prints the libdir name obtained according to Algorithm 11.5. Only + available in EAPIs listed in table 11.25 as supporting get_libdir. +

- -

Algorithm 11.5: get_libdir logic

+class="content">get_libdir logic

- 1: let libdir=lib -
2: + 1: let libdir=lib +
2: if the ABI environment variable is set then -
3: let libvar=LIBDIR_$ABI -
4: +
3: let libvar=LIBDIR_$ABI +
4: if the environment variable named by libvar is set then -
5: let libdir=the value of the variable named by libvar + id="x1-145030r201"> +
5: let libdir=the value of the variable named by libvar -
6: +
6: end if -
7: +
7: end if -
8: print the value of libdir -

- - -

+ id="x1-145033r204"> +
8: print the value of libdir +

Table 11.25: Misc commands for EAPIs

+class="content">Misc commands for EAPIs

11.3.3.15 Debug Commands

+ id="x1-14600011.3.3.15">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 @@ -8967,7 +8881,7 @@ class="ectt-1000">now in section $*.

11.3.3.16 Reserved Commands and Variables

+ id="x1-14700011.3.3.16">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: @@ -8999,11 +8913,11 @@ class="ectt-1000">prep

11.4 The state of the system between functions

+ id="x1-14800011.4">The State of the System Between Functions -

For the sake of this section: -

For the sake of this section: +

Variancy is any package manager action that modifies either ROOT or 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: -

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_ +
There must be no variancy between a package’s pkg_setup and a package’s postinst, except for any variancy introduced by that package. +class="ectt-1000">pkg_postinst, except for any variancy introduced by that package.
Any non-default pkg phase function must be run exclusively. @@ -9046,9 +8959,9 @@ class="ectt-1000">pkg phase function must be run exclusively.
Chapter 12
Merging and Unmerging
+ id="x1-14900012">Merging and Unmerging
Note: In this chapter, file and regular file have their Unix meanings.

12.1 Overview
+ id="x1-15100012.1">Overview
The merge process merges the contents of the D directory onto the filesystem under ROOT. This is @@ -9066,7 +8979,7 @@ specification.

12.2 Directories
+ id="x1-15200012.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

12.2.1 Permissions
+ id="x1-15300012.2.1">Permissions
The owner, group and mode (including set*id and sticky bits) of the directory must be preserved, except as follows:
@@ -9091,7 +9004,7 @@ including modification time, may be discarded.

12.2.2 Empty Directories
+ id="x1-15400012.2.2">Empty directories
Behaviour upon encountering an empty directory is undefined. Ebuilds must not attempt to install @@ -9099,7 +9012,7 @@ an empty directory.

12.3 Regular Files
+ id="x1-15500012.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 @@ -9110,7 +9023,7 @@ regular file or a symlink to a regular file.

12.3.1 Permissions
+ id="x1-15600012.3.1">Permissions
The owner, group and mode (including set*id and sticky bits) of the file must be preserved, except as follows:
@@ -9128,12 +9041,11 @@ discarded.

12.3.2 File modification times
+ id="x1-15700012.3.2">File modification times
MTIME-PRESERVE In EAPIs listed in table 12.1, the package manager must preserve modification +class="eccc1000-">mtime-preserve In EAPIs listed in table 12.1, the package manager must preserve modification times of regular files. This includes files being compressed before merging. Exceptions to this are files newly created by the package manager and binary object files being stripped of symbols. @@ -9161,13 +9073,13 @@ image directory.

Table 12.1: Preservation of file modification times (mtimes)
+class="content">Preservation of file modification times (mtimes)

12.3.3 Configuration File Protection

+ id="x1-15800012.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. +href="#x1-610005.3">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:

@@ -9240,7 +9152,7 @@ class="compactenum">If 9999 is reached in this way, behaviour is undefined.

12.4 Symlinks

+ id="x1-15900012.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 @@ -9251,7 +9163,7 @@ class="ectt-1000">D.

12.4.1 Rewriting

+ id="x1-16000012.4.1">Rewriting

Any absolute symlink whose link starts with D must be rewritten with the leading D removed. The @@ -9261,13 +9173,13 @@ package manager should issue a notice when doing this.

12.5 Hard links

+ id="x1-16100012.5">Hard Links

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

12.6 Other Files

+ id="x1-16200012.6">Other Files

Ebuilds must not attempt to install any other type of file (FIFOs, device nodes etc). @@ -9277,9 +9189,9 @@ files.

Chapter 13
Metadata Cache

+ id="x1-16300013">Metadata Cache

13.1 Directory Contents

+ id="x1-16400013.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 @@ -9291,7 +9203,7 @@ entries.

13.2 Cache File Format

+ id="x1-16500013.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. @@ -9345,7 +9257,7 @@ class="ectt-1000">IUSE) class="compactenum">Use flags that this package requires (REQUIRED_USE). Blank in some EAPIs; see table 7.2. +href="#x1-69002r2">7.2.

13.

Post dependencies (EAPI) class="compactenum">Properties (PROPERTIES). In some EAPIs, may optionally be blank, regardless of ebuild metadata; see table 7.2. +href="#x1-69002r2">7.2.

17.

Defined phases (DEFINED_PHASES). In some EAPIs, may optionally be blank, regardless of ebuild metadata; see table 7.4. +href="#x1-75001r4">7.4.

18.

Blank lines to pad the file to 22 lines long

@@ -9388,7 +9300,7 @@ line 15 if it does not.

Chapter 14
Glossary

+ id="x1-16600014">Glossary

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

@@ -9429,18 +9341,27 @@ class="description">See above. Bibliography + id="x1-16700014">Bibliography + [1]   Michał Górny. + GLEP 68: Package and category metadata. https://wiki.gentoo.org/wiki/GLEP:68, + April 2016. + + + [2]   Marius Mauch. GLEP 44: Manifest2 format. https://wiki.gentoo.org/wiki/GLEP:44, December 2005. - [2]      Jason Stubbs. GLEP 37: Virtuals deprecation. https://wiki.gentoo.org/wiki/GLEP:37, April 2005. + id="x1-167004r238"> Appendix A metadata.xml + id="x1-168000A">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 https://www.gentoo.org/dtd/metadata.dtd. +described in GLEP 68 [1]. + id="x1-168001r238"> Appendix B Unspecified Items + id="x1-169000B">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. @@ -9501,33 +9421,31 @@ class="ectt-1000">PORTDIR_OVERLAY variable, and overlay behaviour in gene + id="x1-169001r238"> 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 + id="x1-170000C">Historical Curiosities + The items described in this chapter are included for information only. Unless otherwise +noted, they were deprecated or abandoned long before EAPI was introduced. Ebuilds +must not use these features, and package managers should not be changed to support +them. + + If-else USE Blocks Historically, Portage supported if-else use conditionals, as shown by listing C.1. The block before +href="#x1-171001r1">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 +class="content">If-else use blocks @@ -9538,14 +9456,14 @@ DEPEND=" taken/if-false ) " - + - C.2 cvs Versions - Portage has very crude support for CVS packages. The package 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 + 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. - + - C.4 Old-style Virtuals - Historically, virtuals were special packages rather than regular ebuilds. An ebuild could specify in + Old-style Virtuals + Historically, virtuals were special packages rather than regular ebuilds. An ebuild could specify in the PROVIDE metadata that it supplied certain virtuals, and the package manager had to bear this in mind when handling dependencies. - Old-style virtuals were supported by EAPIs Old-style virtuals were supported by EAPIs 0, 1, 2, 3 and 4, and were phased out via GLEP 37 [2]. +href="#XGlep37">3]. @@ -9584,12 +9502,12 @@ href="#XGlep37">2]. + id="x1-174001r238"> Appendix D Feature Availability by EAPI + id="x1-175000D">Feature Availability by EAPI Note: This chapter is informative and for convenience only. Refer to the main text for specifics. For lack of space, EAPIs 0, 1, and 2 have been consolidated into a single column in the table below; entries @@ -9598,7 +9516,7 @@ for a complete table of previous EAPIs. + id="x1-176001r1"> - - style="vertical-align:baseline;" id="TBL-50-41-"> class="td11"> AA class="td11"> Option --host-root class="td11"> default function style="vertical-align:baseline;" id="TBL-50-91-"> + id="x1-176003r238"> Appendix E Differences Between EAPIs + id="x1-177000E">Differences Between EAPIs Note: This chapter is informative and for convenience only. Refer to the main text for specifics. - EAPI 0 + EAPI 0 EAPI 0 is the base EAPI. - EAPI 1 + EAPI 1 EAPI 1 is EAPI 0 with the following changes: IUSE defaults, IUSE-DEFAULTS on page 82. +class="eccc1000-">iuse-defaults on page 85. Slot dependencies, SLOT-DEPS on page 119. +class="eccc1000-">slot-deps on page 122. Different src_compile implementation, SRC-COMPILE-1 on page 152. +class="eccc1000-">src-compile-1on page 156. - EAPI 2 + EAPI 2 EAPI 2 is EAPI 1 with the following changes: Use dependencies, USE-DEPS on page 110. +class="eccc1000-">use-deps on page 113. ! and !! blockers, BANG-STRENGTH on page 116. +class="eccc1000-">bang-strength on page 119. SRC_URI arrows, SRC-URI-ARROWS on page 121. +class="eccc1000-">src-uri-arrows on page 125. src_prepare, SRC-PREPARE on page 134. +class="eccc1000-">src-prepare on page 138. src_configure, SRC-CONFIGURE on page 141. +class="eccc1000-">src-configure on page 145. Different src_compile implementation, SRC-COMPILE-2 on page 156. +class="eccc1000-">src-compile-2 on page 160. default_ phase functions for phases pkg_nofetch, src_unpack, src_prepare, src_ +class="ectt-1000">default_ phase functions for phases pkg_nofetch, src_unpack, src_prepare, configure, src_configure, src_compile and src_test; DEFAULT-PHASE-FUNCS on page 181. +class="eccc1000-">default-phase-funcs on page 185. doman language detection by filename, DOMAN-LANGS on page 248. +class="eccc1000-">doman-langs on page 253. default function, DEFAULT-FUNC on page 282. +class="eccc1000-">default-funcon page 284. - EAPI 3 + EAPI 3 EAPI 3 is EAPI 2 with the following changes: Offset-prefix support by definition of EPREFIX, ED and EROOT, OFFSET-PREFIX-VARS +class="eccc1000-">offset-prefix-vars on page 218. +href="#x1-12300011.1.3">222. unpack supports .xz and .tar.xz, UNPACK-EXTENSIONS on page 281. +class="eccc1000-">unpack-extensions on page 283. File modification times are preserved, MTIME-PRESERVE on page 296. +class="eccc1000-">mtime-preserveon page 293. - EAPI 4 + EAPI 4 EAPI 4 is EAPI 3 with the following changes: PROPERTIES support is mandatory, PROPERTIES on page 82. +class="eccc1000-">properties on page 85. REQUIRED_USE, REQUIRED-USE on page 82. +class="eccc1000-">required-use on page 85. RDEPEND=DEPEND no longer done, RDEPEND-DEPEND on page 89. +class="eccc1000-">rdepend-depend on page 92. DEFINED_PHASES support is mandatory, DEFINED-PHASES on page 93. +class="eccc1000-">defined-phases on page 96. Use dependency defaults, USE-DEP-DEFAULTS on page 120. +class="eccc1000-">use-dep-defaults on page 123. S to WORKDIR fallback restricted, S-WORKDIR-FALLBACK on page 124. +class="eccc1000-">s-workdir-fallback on page 128. pkg_pretend, PKG-PRETEND on page 127. +class="eccc1000-">pkg-pretend on page 131. Default src_install no longer a no-op, SRC-INSTALL-4 on page 166. +class="eccc1000-">src-install-4 on page 170. pkg_info can run on non-installed packages, PKG-INFO on page 178. +class="eccc1000-">pkg-info on page 182. AA is gone, AA on page 197. +class="eccc1000-">aa on page 201. KV is gone, KV on page 200. +class="eccc1000-">kv on page 204. MERGE_TYPE, MERGE-TYPE on page 200. +class="eccc1000-">merge-type on page 204. REPLACING_VERSIONS and REPLACED_BY_VERSION, REPLACE-VERSION-VARS on +class="eccc1000-">replace-version-vars on page 215. +href="#x1-12200011.1.2">219. Utilities now die on failure, DIE-ON-FAILURE on page 226, unless called under +class="eccc1000-">die-on-failure on page 230, unless called under nonfatal, NONFATAL on page 226 +class="eccc1000-">nonfatal on page 230 dohard, dosed banned, BANNED-COMMANDS on page 229. +class="eccc1000-">banned-commands on page 233. econf adds --disable-dependency-tracking, ECONF-OPTIONS on page 242. +class="eccc1000-">econf-options on page 247. dodoc -r support, DODOC on page 245. +class="eccc1000-">dodoc on page 250. doins supports symlinks, DOINS on page 247. +class="eccc1000-">doins on page 252. doman -i18n option takes precedence, DOMAN-LANGS on page 248. +class="eccc1000-">doman-langs on page 253. Controllable compression and docompress, DOCOMPRESS on page 267. +class="eccc1000-">docompress on page 269. use_with and use_enable support empty third argument, USE-WITH on page 271. +class="eccc1000-">use-withon page 273. - EAPI 5 + EAPI 5 EAPI 5 is EAPI 4 with the following changes: Stable use masking and forcing, STABLEMASK on page 61. +class="eccc1000-">stablemask on page 64. REQUIRED_USE now supports ?? groups, AT-MOST-ONE-OF on page 103. +class="eccc1000-">at-most-one-of on page 106. Slot operator dependencies, SLOT-OPERATOR-DEPS on page 119. +class="eccc1000-">slot-operator-deps on page 122. SLOT now supports an optional sub-slot part, SUB-SLOT on page 119. +class="eccc1000-">sub-slot on page 122. src_test supports parallel tests, PARALLEL-TESTS on page 163. +class="eccc1000-">parallel-tests on page 167. EBUILD_PHASE_FUNC, EBUILD-PHASE-FUNC on page 200. +class="eccc1000-">ebuild-phase-func on page 204. USE is calculated differently, PROFILE-IUSE-INJECT on page 214. +class="eccc1000-">profile-iuse-inject on page 218. find is guaranteed to be GNU, GNU-FIND on page 222. +class="eccc1000-">gnu-find on page 226. best_version and has_version support the --host-root option, HOST-ROOT-OPTION on page 232. +class="eccc1000-">host-root-option on page 236. econf adds --disable-silent-rules, ECONF-OPTIONS on page 242. +class="eccc1000-">econf-options on page 247. doheader and newheader support, DOHEADER on page 246. +class="eccc1000-">doheader on page 251. new* can read from standard input, NEWFOO-STDIN on page 248. +class="eccc1000-">newfoo-stdin on page 253. usex support, USEX on page 271. +class="eccc1000-">usexon page 273. - EAPI 6 + EAPI 6 EAPI 6 is EAPI 5 with the following changes: Bash version is 4.2, BASH-VERSION on page 75. +class="eccc1000-">bash-version on page 78. Default src_prepare no longer a no-op, SRC-PREPARE-6 on page 134. +class="eccc1000-">src-prepare-6 on page 138. Different src_install implementation, SRC-INSTALL-6 on page 170. +class="eccc1000-">src-install-6 on page 174. LC_CTYPE and LC_COLLATE compatible with POSIX locale, LOCALE-SETTINGS on +class="eccc1000-">locale-settings on page 211. +href="#x1-12000011.1">215. failglob is enabled in global scope, FAILGLOB on page 222. +class="eccc1000-">failglob on page 226. einstall banned, BANNED-COMMANDS on page 229. +class="eccc1000-">banned-commands on page 233. die and assert called with -n respect nonfatal, NONFATAL-DIE on page 233. +class="eccc1000-">nonfatal-die on page 239. eapply support, EAPPLY on page 236. +class="eccc1000-">eapply on page 243. eapply_user support, EAPPLY-USER on page 236. +class="eccc1000-">eapply-user on page 244. econf adds --docdir and --htmldir, ECONF-OPTIONS on page 242. +class="eccc1000-">econf-options on page 247. in_iuse support, IN-IUSE on page 271. +class="eccc1000-">in-iuse on page 273. unpack supports absolute and relative paths, UNPACK-ABSOLUTE on page 280. +class="eccc1000-">unpack-absolute on page 282. unpack supports .txz, UNPACK-EXTENSIONS on page 281. +class="eccc1000-">unpack-extensions on page 283. unpack matches filename extensions case-insensitively, UNPACK-IGNORE-CASE on +class="eccc1000-">unpack-ignore-case on page 282. +href="#x1-14500011.3.3.14">283. einstalldocs support, EINSTALLDOCS on page 282. +class="eccc1000-">einstalldocs on page 284. get_libdir support, GET-LIBDIR on page 282. +class="eccc1000-">get-libdiron page 285. + id="x1-185001r238"> Appendix F Desk Reference - Desk Reference + EAPI Cheat Sheet project. Some of its features have been included in EAPI ̵ ²May change if a package has been updated (see 4.4.4) +class="ecrm-0800">). ³This variable is generally considered deprecated. However, ebuilds must still assume that the package manager sets it in the EAPIs supporting it. For example, a few configure scripts use this variable @@ -11356,10 +11206,10 @@ class="ecrm-0800">This variable is generally considered deprecated. However, ebu class="ecrm-0800">to find the aalib package; ebuilds calling such configure scripts must thus work around this. - ⁴Not necessarily present when installing from a binary package - Not necessarily present when installing from a binary package. Ebuilds must not access the directory in global scope. + ⁵Consistent and preserved across a single connected sequence of install or uninstall phases, but not between install and uninstall. When reinstalling a package, this variable must have different values for Table D.1: Features in EAPIs +class="content">Features in EAPIs + Feature 5 6 + style="vertical-align:baseline;" id="TBL-50-20-"> Stable use masking/forcing stablemask p61 64 No @@ -9668,7 +9586,7 @@ class="td11"> style="vertical-align:baseline;" id="TBL-50-21-"> Bash version bash-version p75 78 3.2 @@ -9684,7 +9602,7 @@ class="td11"> class="td11"> IUSE defaults iuse-defaults p82 85 * @@ -9700,7 +9618,7 @@ class="td11"> class="td11"> REQUIRED_USE required-use p82 85 No @@ -9716,7 +9634,7 @@ class="td11"> class="td11"> PROPERTIES properties p82 85 Optionally @@ -9732,7 +9650,7 @@ class="td11"> class="td11"> RDEPEND=DEPEND rdepend-depend p89 92 Yes @@ -9748,7 +9666,7 @@ class="td11"> class="td11"> DEFINED_PHASES defined-phases p93 96 Optionally @@ -9764,7 +9682,7 @@ class="td11"> class="td11"> ?? ( ) groups at-most-one-of p103 106 No @@ -9780,7 +9698,7 @@ class="td11"> class="td11"> SRC_URI arrows src-uri-arrows p121 125 * @@ -9795,7 +9713,7 @@ class="td11"> style="vertical-align:baseline;" id="TBL-50-29-"> Slot dependencies slot-deps p119 122 * @@ -9814,7 +9732,7 @@ class="td11"> style="vertical-align:baseline;" id="TBL-50-30-"> Sub-slots sub-slot p119 122 No @@ -9829,7 +9747,7 @@ class="td11"> style="vertical-align:baseline;" id="TBL-50-31-"> Use dependencies use-deps p110 113 * @@ -9848,7 +9766,7 @@ class="td11"> class="td11"> ! blockers bang-strength p116 119 * @@ -9864,7 +9782,7 @@ class="td11"> class="td11"> !! blockers bang-strength p116 119 * @@ -9881,7 +9799,7 @@ class="td11"> S to WORKDIR fallback s-workdir-fallback p124 128 Always @@ -9897,7 +9815,7 @@ class="td11"> class="td11"> pkg_pretend pkg-pretend p127 131 No @@ -9913,7 +9831,7 @@ class="td11"> class="td11"> src_prepare src-prepare p134 138 * @@ -9929,7 +9847,7 @@ class="td11"> class="td11"> src_prepare style src-prepare p134 138 * @@ -9945,7 +9863,7 @@ class="td11"> class="td11"> src_configure src-configure p141 145 * @@ -9961,7 +9879,7 @@ class="td11"> class="td11"> src_compile style src-compile p148 152 * @@ -9979,7 +9897,7 @@ class="td11"> Parallel tests parallel-tests p163 167 No @@ -9995,7 +9913,7 @@ class="td11"> class="td11"> src_install style src-install p166 170 no-op @@ -10011,7 +9929,7 @@ class="td11"> class="td11"> pkg_info pkg-info p178 182 Installed @@ -10027,7 +9945,7 @@ class="td11"> class="td11"> default_ phase functions default-phase-funcs p181 185 * @@ -10093,7 +10011,7 @@ class="ectt-1000">src_test aa p197 201 Yes @@ -10109,7 +10027,7 @@ class="td11"> class="td11"> KV kv p200 204 Yes @@ -10128,7 +10046,7 @@ class="td11"> class="td11"> EBUILD_PHASE_FUNC ebuild-phase-func p200 204 No @@ -10144,7 +10062,7 @@ class="td11"> class="td11"> MERGE_TYPE merge-type p200 204 No @@ -10159,7 +10077,7 @@ class="td11"> style="vertical-align:baseline;" id="TBL-50-49-"> Sane locale settings locale-settings p211 215 Undefined @@ -10175,7 +10093,7 @@ class="td11"> class="td11"> Profile IUSE injection profile-iuse-inject p214 218 No @@ -10191,7 +10109,7 @@ class="td11"> class="td11"> REPLACING_VERSIONS replace-version-vars p215 219 No @@ -10207,7 +10125,7 @@ class="td11"> class="td11"> REPLACED_BY_VERSION replace-version-vars p215 219 No @@ -10225,7 +10143,7 @@ class="ectt-1000">EPREFIX, ED, EROOT offset-prefix-vars p218 222 No @@ -10241,7 +10159,7 @@ class="td11"> class="td11"> failglob in global scope failglob p222 226 No @@ -10257,7 +10175,7 @@ class="td11"> class="td11"> find is GNU? gnu-find p222 226 Undefined @@ -10272,7 +10190,7 @@ class="td11"> style="vertical-align:baseline;" id="TBL-50-56-"> Most utilities die die-on-failure p226 230 No @@ -10288,7 +10206,7 @@ class="td11"> class="td11"> nonfatal nonfatal p226 230 No @@ -10304,7 +10222,7 @@ class="td11"> class="td11"> dohard banned-commands p229 233 Yes @@ -10320,7 +10238,7 @@ class="td11"> class="td11"> dosed banned-commands p229 233 Yes @@ -10336,7 +10254,7 @@ class="td11"> class="td11"> einstall banned-commands p229 233 Yes @@ -10355,7 +10273,7 @@ class="td11"> host-root-option p232 236 No @@ -10371,7 +10289,7 @@ class="td11"> class="td11"> die -n nonfatal-die p233 239 No @@ -10387,7 +10305,7 @@ class="td11"> class="td11"> eapply eapply p236 243 No @@ -10403,7 +10321,7 @@ class="td11"> class="td11"> eapply_user eapply-user p236 244 No @@ -10422,7 +10340,7 @@ class="td11"> class="td11"> econf arguments econf-options p242 247 @@ -10452,7 +10370,7 @@ class="td11"> class="td11"> dodoc -r dodoc p245 250 No @@ -10468,7 +10386,7 @@ class="td11"> class="td11"> doheader doheader p246 251 No @@ -10484,7 +10402,7 @@ class="td11"> class="td11"> doins handles symlinks doins p247 252 No @@ -10500,7 +10418,7 @@ class="td11"> class="td11"> doman languages doman-langs p248 253 * @@ -10516,7 +10434,7 @@ class="td11"> class="td11"> doman -i18n precedence doman-langs p248 253 * @@ -10532,7 +10450,7 @@ class="td11"> class="td11"> new* support stdin newfoo-stdin p248 253 No @@ -10547,7 +10465,7 @@ class="td11"> style="vertical-align:baseline;" id="TBL-50-73-"> Controllable compression docompress p267 269 No @@ -10563,7 +10481,7 @@ class="td11"> class="td11"> docompress docompress p267 269 No @@ -10579,7 +10497,7 @@ class="td11"> class="td11"> use_with empty third arg use-with p271 273 No @@ -10595,7 +10513,7 @@ class="td11"> class="td11"> usex usex p271 273 No @@ -10611,7 +10529,7 @@ class="td11"> class="td11"> in_iuse in-iuse p271 273 No @@ -10627,7 +10545,7 @@ class="td11"> class="td11"> unpack absolute paths unpack-absolute p280 282 No @@ -10644,7 +10562,7 @@ class="td11"> unpack support for xz unpack-extensions p281 283 No @@ -10661,7 +10579,7 @@ class="td11"> unpack support for txz unpack-extensions p281 283 No @@ -10680,7 +10598,7 @@ class="td11"> class="td11"> unpack case-insensitive unpack-ignore-case p282 283 No @@ -10699,7 +10617,7 @@ class="td11"> default-func p282 284 * @@ -10715,7 +10633,7 @@ class="td11"> class="td11"> einstalldocs einstalldocs p282 284 No @@ -10731,7 +10649,7 @@ class="td11"> class="td11"> get_libdir get-libdir p282 285 No @@ -10746,7 +10664,7 @@ class="td11"> style="vertical-align:baseline;" id="TBL-50-86-"> File mtimes preserved mtime-preserve p296 293 Undefined @@ -10771,8 +10689,8 @@ class="td11">

Contents

List of Algorithms

List of Listings

List of Tables

Acknowledgements

Copyright and Licence

Reporting Issues

Chapter 1Introduction

1.1 Aims and Motivation

1.2 Rationale

1.3 Conventions

Chapter 2EAPIs

2.1 Definition

2.2 Defined EAPIs

2.3 Reserved EAPIs

Chapter 3Names 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.1.7 Keyword names

3.1.7 EAPI Names

3.2 Version Specifications

3.3 Version Comparison

3.4 Uniqueness of versions

Chapter 4Tree 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

Chapter 5Profiles

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 Simple line-based files

5.2.6 packages

5.2.7 packages.build

5.2.8 package.mask

5.2.9 package.provided

5.2.10 package.use

5.2.11 USE masking and forcing

5.3 Profile variables

5.3.1 Incremental Variables

5.3.2 Specific variables and their meanings

Chapter 6Ebuild File Format

Chapter 7Ebuild-defined Variables

7.1 Metadata invariance

7.2 Mandatory Ebuild-defined Variables

7.3 Optional Ebuild-defined Variables

7.3.1 EAPI

7.3.2 Keywords

7.3.3 RDEPEND value

7.4 Magic Ebuild-defined Variables

Chapter 8Dependencies

8.1 Dependency Classes

8.2 Dependency Specification Format

8.2.1 All-of Dependency Specifications

8.2.2 Use-conditional Dependency Specifications

8.2.3 Any-of Dependency Specifications

8.2.4 Exactly-one-of Dependency Specifications

8.2.5 At-most-one-of Dependency Specifications

8.2.6 Package Dependency Specifications

8.2.6.1 Operators

8.2.6.2 Block Operator

8.2.6.3 Slot Dependencies

8.2.6.4 2-Style and 4-Style Use Dependencies

Chapter 1
Introduction

Chapter 2
EAPIs

Chapter 3
Names and Versions

Chapter 4
Tree Layout

Chapter 5
Profiles

Chapter 6
Ebuild File Format

Chapter 7
Ebuild-defined Variables

Chapter 8
Dependencies

Chapter 9
Ebuild-defined Functions

Chapter 10
Eclasses

Chapter 11
The Ebuild Environment

Chapter 12
Merging and Unmerging