@@ -, +, @@ --- dependencies.tex | 34 +++++++++++++++++++++++++++++++--- eapi-differences.tex | 4 ++++ ebuild-vars.tex | 27 +++++++++++++++++---------- eclasses.tex | 8 ++++---- metadata-cache.tex | 5 +++-- 5 files changed, 59 insertions(+), 19 deletions(-) --- a/dependencies.tex +++ a/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 An only-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{only-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{Only-one-of Dependency Specifications} + +Any use-conditional group that is an immediate child of an only-one-of group, if not enabled +(disabled for an exclamation mark prefixed use flag name), is not considered a member of the +only-one-of group for match purposes. + +In an only-one-of group, exactly one immediate child element must be matched. + +An empty only-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,17 @@ 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). + +If the package manager encounters a package version where \t{REQUIRED\_USE} assertions are not met, +it must treat this package version as if it was masked. No phase functions must be called. + +It is an error for a flag to be used if it is not included in \t{IUSE\_EFFECTIVE}. + \subsection{Restrict} \label{sec:restrict} --- a/eapi-differences.tex +++ a/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}. --- a/ebuild-vars.tex +++ a/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} --- a/eclasses.tex +++ a/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} --- a/metadata-cache.tex +++ a/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 --