Re: [gentoo-pms] EAPI specification in ebuilds

[Ulrich Mueller]

>>>>> On Sat, 7 Apr 2012, Ulrich Mueller wrote:

>>>>> On Fri, 6 Apr 2012, David Leverton wrote:
>>> Right, assigning the same EAPI twice would be an example for an
>>> ebuild that is invalid but accepted by the package manager. But
>>> would this cause any problems?

>> It's not that it's a problem in itself, it just struck me as an edge
>> case with the potential for implementations to differ.  As long as
>> everyone's clear what the rules are it's fine.

> Maybe the spec should say that the first match must be used:

> "The package manager may optionally determine the EAPI of an ebuild by
> parsing it, using the first match for the above regular expression
> within the above line number limit."

See updated patch below.

Ulrich


--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -75,7 +75,7 @@
 
 \begin{description}
 \item[DEPEND] See section~\ref{sec:dependencies}.
-\item[EAPI] The EAPI. See below for defaults.
+\item[EAPI] The EAPI. See below.
 \item[PDEPEND] See section~\ref{sec:dependencies}.
 \item[RDEPEND] See section~\ref{sec:dependencies}. For some EAPIs, \t{RDEPEND} has special behaviour
     for its value if unset and when used with an eclass. See section~\ref{sec:rdepend-depend} for
@@ -124,6 +124,23 @@
 If any of these variables are set to invalid values, the package manager's behaviour is undefined;
 ideally, an error in one ebuild should not prevent operations upon other ebuilds or packages.
 
+To enable parsing of ebuilds for the \t{EAPI} value, the \t{EAPI} assignment statement must adhere
+to the following syntax: It must consist of the string \t{EAPI}, followed by an equals sign,
+followed by the \t{EAPI} value, optionally enclosed in single or double quotes. The statement must
+be on its own line, optionally preceded or followed by whitespace (spaces or tabs), optionally
+followed by a comment. Thus, the line must match the following regular expression:
+\begin{verbatim}
+^[ \t]*EAPI=(['"]?)([A-Za-z0-9+_.-]*)\1[ \t]*(#.*)?$
+\end{verbatim}
+If an ebuild contains an \t{EAPI} assignment, the statement must occur within the first 20 lines.
+An ebuild must not contain more than one \t{EAPI} assignment.
+
+The package manager may optionally determine the \t{EAPI} of an ebuild by parsing it, using the
+first match for the above regular expression within the above line number limit. If a recognised
+\t{EAPI} has been determined such, then the package manager must make sure that the \t{EAPI} value
+obtained by sourcing the ebuild with bash is identical to the one obtained by parsing. The ebuild
+must be treated as invalid if these values are different.
+
 \subsection{\t{RDEPEND} value}
 \label{sec:rdepend-depend}