Future EAPI/Alternate EAPI mechanisms

This is a working page for collecting the different proposals how the EAPI should be specified in future. See also the previous discussion.

Parse the EAPI assignment statement
This first proposal would require that the syntax of the EAPI assignment statement in ebuilds matches a well defined regular expression. A scan of the Portage tree shows that the statement only occurs in the following variations (using EAPI 4 as example):
 * EAPI=4
 * EAPI="4"
 * EAPI='4'

Sometimes this is followed by whitespace or a comment (starting with a # sign). Also, with very few exceptions the EAPI assignment occurs within the first few lines of the ebuild. For the vast majority of ebuilds it is in line 5.

Written in a more formal way, appropriate for a specification:
 * Ebuilds must contain at most one EAPI assignment statement.
 * It must occur within the first N lines of the ebuild (N=10 and N=30 have been suggested).
 * The statement must match the following regular expression (extended regexp syntax):
 * ^[ \t]*EAPI=(['"]?)([A-Za-z0-9._+-]*)\1[ \t]*(#.*)?$

Note: The first and the third point are already fulfilled by all ebuilds in the Portage tree. The second point will require very few ebuilds to be changed (9 packages for N=10, or 2 packages for N=30).

The package manager would determine the EAPI by parsing the assignment with above regular expression. A sanity check would be added. Citing Zac Medico: "The fact that we can compare the probed EAPI to the actual EAPI variable after the ebuild is sourced seems like a perfect sanity check. We could easily detect inconsistencies and flag such ebuilds as invalid, providing a reliable feedback mechanism to ebuild developers."

Pros

 * No modifications to the tree required.
 * Uniform style of assignment throughout all EAPIs.

Cons

 * Cannot be used in other languages than bash (unless they allow for multiline comments).

EAPI in header comment
A different approach would be to specify the EAPI in a specially formatted comment in the first line of the ebuild's header. The syntax could be one of the following:
 * The word "ebuild", followed by whitespace, followed by the EAPI, followed by end-of-line or whitespace. Corresponding regexp:
 * \<ebuild[ \t]([A-Za-z0-9._+-]*)($|[ \t])
 * The word "EAPI", followed by an equals sign ("="), followed by the EAPI, followed by end-of-line or whitespace. Corresponding regexp:
 * \<EAPI=([A-Za-z0-9._+-]*)($|[ \t])

The usual EAPI assignment statement in the ebuild would be still required, at least for a transition period. A sanity check similar to the one mentioned above would be added. Alternatively, a statement like
 * : ${EAPI=5}

or
 * ${EAPI} || { EAPI=-1; return; }

could be added and the variable be made read-only, too.

Pros

 * Clean and well-defined solution when the transition is finished.
 * Allows for changes of global scope behaviour,
 * Can be used not only for bash, but also for other languages.

Cons

 * Duplicate EAPI specification in ebuilds during a transition period.

EAPI in header comment and one-time change of file extension
As before, but combined with a one time change of the file extension, like .ebuild → .eb. (Note: It was pointed out that "eb" should be avoided because of its meaning in Russian.)

The EAPI variable could be made read-only in bash before sourcing the ebuild.

Pros

 * Allows for changes of global scope behaviour,
 * Can be used not only for bash, but also for other languages.

Cons

 * Two different file extensions for ebuilds. (But in principle, we could move everything to the new extension later.)

EAPI in filename