[patch] Proposed patch for PMS

0001-REQUIRED_USE-in-EAPI-4-bug-347353.patch (text/plain), 9.84 KB, created by Ulrich Müller on 2010-12-04 08:23:36 UTC

From 6c55308380847e06fbc0aea6bd960859cbce3835 Mon Sep 17 00:00:00 2001
From: Ulrich Mueller <[e-mail]>
Date: Sat, 4 Dec 2010 09:24:39 +0100
Subject: [PATCH] REQUIRED_USE in EAPI 4, bug 347353.

---
 dependencies.tex     |   31 ++++++++++++++++++++++++++++---
 eapi-differences.tex |    4 ++++
 ebuild-vars.tex      |   27 +++++++++++++++++----------
 eclasses.tex         |    8 ++++----
 metadata-cache.tex   |    5 +++--
 5 files changed, 56 insertions(+), 19 deletions(-)

diff --git a/dependencies.tex b/dependencies.tex
index e663a67..d2acd30 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -13,8 +13,8 @@ There are three classes of dependencies supported by ebuilds:
 \item Post dependencies (\t{PDEPEND}). These must be installed at some point.
 \end{compactitem}
 
-In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{PROVIDE}, \t{RESTRICT}, \t{PROPERTIES} and \t{LICENSE}
-use dependency-style specifications to specify their values.
+In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{PROVIDE}, \t{RESTRICT}, \t{PROPERTIES}, \t{LICENSE} and
+\t{REQUIRED\_USE} use dependency-style specifications to specify their values.
 
 \section{Dependency Specification Format}
 
@@ -31,6 +31,7 @@ be surrounded on both sides by whitespace, except at the start and end of the st
     \t{SRC\_URI}.  For \t{SRC\_URI} behaviour, see section~\ref{sec:src-uri-behaviour}.
 \item A flat filename. Permitted in \t{SRC\_URI}.
 \item A license name (e.\,g.\ \t{GPL-2}). Permitted in \t{LICENSE}.
+\item A use flag name, optionally preceded by an exclamation mark. Permitted in \t{REQUIRED\_USE}.
 \item A simple string. Permitted in \t{RESTRICT} and \t{PROPERTIES}.
 \item An all-of group, which consists of an open parenthesis, followed by whitespace,
     followed by zero or more of (a dependency item of any kind followed by whitespace), followed
@@ -41,7 +42,13 @@ be surrounded on both sides by whitespace, except at the start and end of the st
     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 ::= '||' whitespace '(' whitespace (item whitespace)* ')'}.
-    Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{LICENSE}.
+    Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{LICENSE}, \t{REQUIRED\_USE}.
+\item A 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 parenthesis.
+    More formally: \t{one-of ::= '\textasciicircum\textasciicircum' whitespace '(' whitespace
+    (item whitespace)* ')'}.
+    Permitted in \t{REQUIRED\_USE}.
 \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
@@ -90,6 +97,16 @@ considered to be matched if its associated package dependency specification is n
 
 An empty any-of group counts as being matched.
 
+\subsection{One-of Dependency Specifications}
+
+Any use-conditional group that is an immediate child of a one-of group, if not enabled (disabled
+for an exclamation mark prefixed use flag name), is not considered a member of the one-of group for
+match purposes.
+
+In a one-of group, exactly one immediate child element must be matched.
+
+An empty one-of group counts as being matched.
+
 \subsection{Package Dependency Specifications}
 
 A package dependency can be in one of the following base formats. A package manager must warn or
@@ -257,6 +274,14 @@ would not have to be part of \t{IUSE}.
 It is an error for an ebuild to use a conditional use dependency when that ebuild does not have the
 flag in \t{IUSE\_EFFECTIVE}.
 
+\subsection{Use State Constraints}
+\label{sec:required-use}
+\t{REQUIRED\_USE} contains a list of assertions that must be met by the configuration of \t{USE}
+flags to be valid for this ebuild. In order to be matched, a \t{USE} flag in a terminal element
+must be enabled (or disabled if it has an exclamation mark prefix).
+
+It is an error for a flag to be used if it is not included in \t{IUSE\_EFFECTIVE}.
+
 \subsection{Restrict}
 \label{sec:restrict}
 
diff --git a/eapi-differences.tex b/eapi-differences.tex
index 1cd028e..cb9d41d 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -42,6 +42,9 @@ Profile \t{IUSE} injection & \compactfeatureref{profile-iuse-injection} &
 \t{IUSE} defaults & \compactfeatureref{iuse-defaults} &
     No & Yes & Yes & Yes & Yes \\
 
+\t{REQUIRED\_USE} & \compactfeatureref{required-use} &
+    No & No & No & No & Yes \\
+
 \t{PROPERTIES} & \compactfeatureref{properties} &
     Optionally & Optionally & Optionally & Optionally & Yes \\
 
@@ -208,6 +211,7 @@ EAPI 4 is EAPI 3 with the following changes:
 
 \begin{compactitem}
 \item \t{PROPERTIES} support is mandatory, \featureref{properties}.
+\item \t{REQUIRED\_USE}, \featureref{required-use}.
 \item \t{RDEPEND=DEPEND} no longer done, \featureref{rdepend-depend}.
 \item \t{DEFINED\_PHASES} support is mandatory, \featureref{defined-phases}.
 \item Slot operator dependencies, \featureref{slot-operator-deps}.
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 72996d8..db4d50d 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -86,24 +86,31 @@ Ebuilds may define any of the following variables:
 \item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{sec:restrict}
     for value meanings and section~\ref{sec:dependencies} for full syntax.
 \item[PROPERTIES] \featurelabel{properties} Zero or more properties for this package. See
-    section~\ref{sec:properties} for value meanings and section~\ref{sec:dependencies} for full syntax.
-    For EAPIs listed in table~\ref{tab:properties-table} as having optional support, ebuilds must not
-    rely upon the package manager recognising or understanding this variable in any way.
+    section~\ref{sec:properties} for value meanings and section~\ref{sec:dependencies} for full
+    syntax. For EAPIs listed in table~\ref{tab:optional-vars-table} as having optional support,
+    ebuilds must not rely upon the package manager recognising or understanding this variable in
+    any way.
+\item[REQUIRED\_USE] \featurelabel{required-use} Zero or more assertions that must be met by the
+    configuration of \t{USE} flags to be valid for this ebuild. See section~\ref{sec:required-use}
+    for description and section~\ref{sec:dependencies} for full syntax. Only in EAPIs listed in
+    table~\ref{tab:optional-vars-table} as supporting \t{REQUIRED\_USE}.
 \item[S] The path to the temporary build directory, used by \t{src\_compile}, \t{src\_install}
     etc. Defaults to \t{\$\{WORKDIR\}/\$\{P\}}.
 \end{description}
 
-\begin{centertable}{EAPIs supporting \t{PROPERTIES}} \label{tab:properties-table}
-    \begin{tabular}{ l l }
+\begin{centertable}{EAPIs supporting various ebuild-defined variables}
+\label{tab:optional-vars-table}
+    \begin{tabular}{ l l l }
         \toprule
         \multicolumn{1}{c}{\textbf{EAPI}} &
         \multicolumn{1}{c}{\textbf{Supports \t{PROPERTIES}?}} \\
+        \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED\_USE}?}} \\
         \midrule
-    \t{0} & Optionally \\
-    \t{1} & Optionally \\
-    \t{2} & Optionally \\
-    \t{3} & Optionally \\
-    \t{4} & Yes \\
+    \t{0} & Optionally & No \\
+    \t{1} & Optionally & No \\
+    \t{2} & Optionally & No \\
+    \t{3} & Optionally & No \\
+    \t{4} & Yes & Yes \\
     \bottomrule
     \end{tabular}
 \end{centertable}
diff --git a/eclasses.tex b/eclasses.tex
index b3ad13b..c8fee9e 100644
--- a/eclasses.tex
+++ b/eclasses.tex
@@ -34,10 +34,10 @@ The \t{inherit} command must also ensure that:
 
 \section{Eclass-defined Metadata Keys}
 
-The \t{IUSE}, \t{DEPEND}, \t{RDEPEND} and \t{PDEPEND} variables are handled specially
-when set by an eclass. They must be accumulated across eclasses, appending the value set by each
-eclass to the resulting value after the previous one is loaded. Then the eclass-defined value is
-appended to that defined by the ebuild. In the case of \t{RDEPEND}, this is done after the
+The \t{IUSE}, \t{REQUIRED\_USE}, \t{DEPEND}, \t{RDEPEND} and \t{PDEPEND} variables are handled
+specially when set by an eclass. They must be accumulated across eclasses, appending the value set
+by each eclass to the resulting value after the previous one is loaded. Then the eclass-defined
+value is appended to that defined by the ebuild. In the case of \t{RDEPEND}, this is done after the
 implicit \t{RDEPEND} rules in section~\ref{sec:rdepend-depend} are applied.
 
 \section{EXPORT\_FUNCTIONS}
diff --git a/metadata-cache.tex b/metadata-cache.tex
index 70afe2f..8e7a09d 100644
--- a/metadata-cache.tex
+++ b/metadata-cache.tex
@@ -26,12 +26,13 @@ order. Other lines may be present following these; their meanings are not define
 \item Package keywords (\t{KEYWORDS})
 \item Inherited eclasses (\t{INHERITED})
 \item Use flags that this package respects (\t{IUSE})
-\item No longer used; this line is to be ignored.
+\item Use flags that this package requires (\t{REQUIRED\_USE}).
+    Blank in some EAPIs; see table~\ref{tab:optional-vars-table}.
 \item Post dependencies (\t{PDEPEND})
 \item Old-style virtuals provided by this package (\t{PROVIDE})
 \item The ebuild API version to which this package conforms (\t{EAPI})
 \item Properties (\t{PROPERTIES}). In some EAPIs, may optionally be blank, regardless of ebuild
-    metadata; see table~\ref{tab:properties-table}.
+    metadata; see table~\ref{tab:optional-vars-table}.
 \item Defined phases (\t{DEFINED\_PHASES}). In some EAPIs, may optionally be blank, regardless of
     ebuild metadata; see table~\ref{tab:defined-phases-table}.
 \item Blank lines to pad the file to 22 lines long
-- 
1.7.3.2