Abstract

This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for example, foo-1.2.3.ebuild-1). This GLEP prefers simple solutions over complex ones.

Background

Determining what EAPI an ebuild utilizes requires sourcing the ebuild. Sourcing the ebuild currently uses an EAPI-0 environment to maintain compatability. If the EAPI was known in advance the package manager could use a more featureful environment to source ebuilds. An inexhaustive list of features is listed here.

1. Changing the behavior of inherit in specific ways. We assume EAPI-0 so if a given ebuild depends on new behavior of inherit it will not get it.
2. Adding new global scope functions. We assume EAPI-0 so if those functions are called the ebuild will break currently.
3. Requiring a new version of bash (such as bash 4.0.) We assume EAPI-0 which does not use bash v4. If an ebuild depends on bash v4 it will break.
4. Extend versioning rules in an EAPI - for example, addition of the scm suffix - GLEP54 [1].
5. Backwards incompatable EAPI changes. We assume EAPI-0 which implies a specific environment for sourcing. If an ebuild relies features that are not in EAPI-0 during the DEPEND phase then the ebuild may not function properly.

The hope is that the solution presented meets all of these needs.

Non goals

This GLEP accepts that some solutions are 'prettier' than others but in general prefers simple and functional solutions over 'prettier' ones.

Abstract solution

A solution to this problem has to enable these new features to work and one

way to do it is to make the EAPI of an ebuild available to the package managers before those EAPI features are used.

Alternative solutions

A number of other implementations of this GLEP were considered and discarded. They are listed below along with why they were deemed insufficient.

1. Embed the EAPI value in a specific place in the build.

• This change itself is a backwards incompatable EAPI change which breaks requirement 5.
• This change does not meet requirement 4 because it does not allow version changes.
• This idea adds an unknown amount of disk access for the open() and read() calls to find the EAPI on said line.

2. Do 1, but with a new suffix that preserves backwards compatability.

• Same as 1 except it meets requirement 4.
• Potentially confusing; but probably not moreso than the GLEP itself which already proposes new suffixes.
• When more incompatable EAPI changes are proposed; there is a risk that this debate will be had again regarding what to call said suffix.

3. A new subdirectory for ebuilds with EAPI that is not 0, 1, or 2. Alternatively a new subdirectory for ebuilds that that is per-EAPI.

• This idea requires directories as part of the ebuild name (since without the directory the package manager should assume EAPI-0). This is more complex than some other solutions and significant user error may result from its impelmentation.
• A unknown number of added directories and calls to (open/read)dir. O(N) where N is the number of EAPIs that are not 0, 1, 2, or all EAPIs depending on implementation.

4. EAPI is a global scope function ("eapi 3" for example). When called with a supported EAPI value the package manager should modify the execution environment to be compliant with said EAPI.

• This idea requires eapi N to be at the top of the ebuild and breaks if any global scope functions are called. (Read as: fragile)
• This idea does not meet requirement 3 without a complicated multi-sourcing system (to switch bash versions).
• This idea does not meet requirement 5 because older package managers do not know about the eapi function.
• This idea does not meet requirement 4 because it does not allow version scheme changes.
• Requirement 5 may be met with a per-repo bashrc; but would probably be gentoo-x86 specific.
• Requirement 5 may be partially met via "eapi N || die" causing unsupported ebuilds to be rejected by package managers that don't support them.

5. EAPI is stored in metadata.xml.

• This idea does not meet requirement 5 because package managers that do not have support for reading from metadata.xml will assume EAPI-0.
• This idea requires 1 extra open and read call per ebuild regeneration.
• Not the most usable idea; typically ebuild data is bound to ebuilds and data in metadata.xml is not ebuild specific.

Proposed solution

The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This allows package managers to trivially read the EAPI from the ebuild filename.

• It meets requirement 1 because the package manager can change the behavior of inherit before inherit is called.
• It meets requirement 2 because because new global scope functions can be placed in the execution environment before the ebuild is sourced.
• It meets requirement 3 if we bind specific versions of bash to specific EAPIs; if the EAPI is known ahead of time so will the bash version.
• It meets requirement 4 because package managers can determine the EAPI ahead of time and can apply the appropriate versioning rules.
• It meets requirement 5 because old package managers will ignore files that do not end in .ebuild.

Specification

Ebuild filename extension syntax: ebuild[-<EAPI>], where [] denotes an optional part, and <EAPI> is the EAPI of the ebuild.

Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI used by the ebuild can be established by following these steps:

• If the pre-source EAPI is not set it defaults to 0.
• If the pre-source EAPI is not recognised it is returned immediately.
• If the post-source EAPI is not set, it defaults to the pre-source EAPI.
• post-source EAPI is returned.

The above process should be only used to generate the metadata cache. Should the pre-source EAPI be unsupported the cache entry cannot be generated.

Ebuilds with unsupported EAPIs are masked.

QA tools should consider it an error for both EAPIs to be set explicitly to different values. Package managers may warn, but must use the post-source EAPI in such cases.

Examples:

• pkg-1.ebuild, no EAPI set inside the ebuild

  pre-source EAPI defaults to 0, post-source EAPI defaults to pre-source EAPI. EAPI 0 is used.

• pkg-2.ebuild-1, no EAPI set inside the ebuild

  pre-source EAPI is 1, post-source EAPI defaults to pre-source EAPI. EAPI 1 is used.

• pkg-3.ebuild, EAPI="1"

  pre-source EAPI defaults to 0, post-source EAPI is 1. EAPI 1 is used.

• pkg-4.ebuild-2, EAPI="1"

  pre-source EAPI is 2, post-source EAPI is 1. EAPI 1 is used, but note that one should never explicitly set both EAPIs to different values.

• pkg-5.ebuild-2, no EAPI set inside the ebuild, package manager not supporting EAPI 2

  pre-source EAPI is 2, post-source EAPI is never checked. ebuild is masked because of the unsupported pre-source EAPI.

• pkg-6.ebuild, EAPI="2", package manager not supporting EAPI 2

  pre-source EAPI defaults to 0, post-source EAPI is 2 (assuming the package manager didn't die when sourcing the ebuild thinking that EAPI 0 is used). ebuild is masked because of the unsupported post-source EAPI.

Note that it is still not permitted to have more than one ebuild with equal category, package name, and version. Although it would have the advantage of allowing authors to provide backwards compatible ebuilds, it would introduce problems too. The first is the requirement to have strict EAPI ordering, the second is ensuring that all the ebuilds for a single category/package-version are equivalent, i.e. installing any of them has exactly the same effect on a given system.

Application

Note that the developers should only set the pre-source EAPI. The process described above is only necessary to avoid undefined behaviour in corner cases and to retain backwards compatibility.

QA tools may warn if the post-source EAPI is set at all, thus helping with the transition to the new format.

References

Copyright

This document has been placed in the public domain.