[gentoo-pms] [PATCH 26/28] EAPI 7 has binding leftmost-of dep groups (||=).

[Michał Górny]

Bug: https://bugs.gentoo.org/489458
---
 dependencies.tex     | 45 ++++++++++++++++++++++++++++++++++++++-------
 eapi-differences.tex |  4 ++++
 2 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/dependencies.tex b/dependencies.tex
index 5773aef..d9592d9 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -98,6 +98,12 @@ be surrounded on both sides by whitespace, except at the start and end of the st
     of (a dependency item of any kind followed by whitespace), followed by a close parenthesis.
     More formally: \t{any-of} \t{::=} \t{'||' whitespace '(' whitespace (item whitespace)* ')'}.
     Permitted in \t{DEPEND}, \t{BDEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{LICENSE}, \t{REQUIRED_USE}.
+\item \featurelabel{binding-leftmost-of} A binding leftmost-of group, which consists of the string
+    \t{||=}, followed by whitespace, followed by an open parenthesis, followed by whitespace,
+    followed by zero or more of (a dependency item of any kind followed by whitespace), followed by
+    a close parenthesis.  More formally: \t{any-of} \t{::=} \t{'||=' whitespace '(' whitespace (item
+    whitespace)* ')'}.  Permitted in \t{DEPEND}, \t{BDEPEND}, \t{RDEPEND}, \t{PDEPEND} in EAPIs
+    listed in table~\ref{tab:dep-group-table} as supporting \t{||=}\ groups.
 \item An exactly-one-of group, which consists of the string \t{\textasciicircum\textasciicircum},
     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
@@ -109,7 +115,7 @@ be surrounded on both sides by whitespace, except at the start and end of the st
     zero or more of (a dependency item of any kind followed by whitespace), followed by a close
     parenthesis. More formally: \t{at-most-one-of} \t{::=} \t{'??'\ whitespace '(' whitespace
     (item whitespace)* ')'}. Permitted in \t{REQUIRED_USE} in EAPIs listed in
-    table~\ref{tab:at-most-one-of-table} as supporting \t{REQUIRED_USE ??}\ groups.
+    table~\ref{tab:dep-group-table} as supporting \t{REQUIRED_USE ??}\ groups.
 \item A use-conditional group, which consists of an optional exclamation mark, followed by
     a use flag name, followed by a question mark, followed by whitespace, followed by
     an open parenthesis, followed by whitespace, followed by zero or more of (a dependency item
@@ -150,15 +156,17 @@ In particular, note that whitespace is not optional.
 \end{centertable}
 
 \ChangeWhenAddingAnEAPI{7}
-\begin{centertable}{EAPIs supporting \t{REQUIRED_USE ??}\ groups}
-    \label{tab:at-most-one-of-table}
-    \begin{tabular}{ll}
+\begin{centertable}{EAPIs supporting additional group types}
+    \label{tab:dep-group-table}
+    \begin{tabular}{lll}
       \toprule
       \multicolumn{1}{c}{\textbf{EAPI}} &
-      \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED_USE ??}\ groups?}} \\
+      \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED_USE ??}\ groups?}} &
+      \multicolumn{1}{c}{\textbf{Supports \t{||=}\ groups?}} \\
       \midrule
-      0, 1, 2, 3, 4     & No  \\
-      5, 6, 7           & Yes \\
+      0, 1, 2, 3, 4     & No  & No  \\
+      5, 6              & Yes & No  \\
+      7                 & Yes & Yes \\
       \bottomrule
     \end{tabular}
 \end{centertable}
@@ -186,6 +194,29 @@ considered to be matched if its associated package dependency specification is n
 
 An empty any-of group counts as being matched.
 
+\subsection{Binding leftmost-of dependency specifications}
+
+Any use-conditional group that is an immediate child of a binding leftmost-of group, if not enabled
+(disabled for an exclamation mark prefixed use flag name), is not considered a member of the binding
+leftmost-of group for match purposes.
+
+In a binding leftmost-of group, at least one immediate child element must be matched. A blocker is
+considered to be matched if its associated package dependency specification is not matched.
+In addition, for runtime dependencies, indicates that the package will break unless the dependency
+corresponding to the first immediate child (in order of listing) matched in \t{ESYSROOT} at the time
+the package was built is satisfied.
+
+An empty binding leftmost-of group counts as being matched.
+
+To implement the binding leftmost-of operator, the package manager will need to store which of
+the immediate child elements were matched. This syntax is only for package manager use and must not
+be used by ebuilds. Only the first matched child element needs to be indicated.
+
+Whenever the binding leftmost-of group is used in an enabled dependency group, the dependencies
+(\t{DEPEND}) must ensure that at least one of the immediate child elements is also matched at build
+time. It is invalid to use the binding leftmost-of group inside PDEPEND or inside any-of dependency
+specifications.
+
 \subsection{Exactly-one-of dependency specifications}
 
 Any use-conditional group that is an immediate child of an exactly-one-of group, if not enabled
diff --git a/eapi-differences.tex b/eapi-differences.tex
index 87ce708..a89f5f8 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -41,6 +41,9 @@ of this document for a complete table of previous EAPIs.
 \bottomrule
 \endlastfoot
 
+\t{||=} dependency group & \compactfeatureref{binding-leftmost-of} &
+    No & No & No & No & Yes \\
+
 \t{REQUIRED_USE} autoenforced & \compactfeatureref{auto-req-use} &
     No & No & No & No & Yes \\
 
@@ -467,6 +470,7 @@ EAPI 7 is EAPI 6 with the following changes:
   \featureref{nonfatal-fallback}.
 \item \t{die} guaranteed to work in a subshell environment, \featureref{subshell-die}.
 \item automatic enforcing of \t{REQUIRED_USE} is supported, \featureref{auto-req-use}.
+\item binding leftmost-of (\t{||=}) dependency group is supported, \featureref{binding-leftmost-of}.
 \end{compactitem}
 
 \ChangeWhenAddingAnEAPI{7}
-- 
2.14.2