commit: b7d98a29242722f0224449f52d3cbabcf5c44c92
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Wed Oct 4 16:10:08 2017 +0000
Commit: Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Wed Oct 4 16:47:08 2017 +0000
URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=b7d98a29
EAPI 7 has automatic USE enforcing.
dependencies.tex | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++-
eapi-differences.tex | 4 ++++
profiles.tex | 1 +
3 files changed, 72 insertions(+), 1 deletion(-)
diff --git a/dependencies.tex b/dependencies.tex
index 63d8c53..5773aef 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -384,16 +384,82 @@ It is an error for an ebuild to use a conditional use
dependency when that ebuil
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 should attempt to automatically enforce the necessary flags as detailed
+in section~\ref{sec:enforce-required-use}. If this feature is not supported or
it fails to resolve
+the problem, the package manager must treat this package version as if it was
masked. No phase
+functions must be called in that case.
It is an error for a flag to be used if it is not included in
\t{IUSE_EFFECTIVE}.
+\subsubsection{Automatic enforcing of REQUIRED_USE}
+\label{sec:enforce-required-use}
+
+\featurelabel{auto-req-use} In EAPIs listed in
table~\ref{tab:enforce-required-use-table} as
+supporting enforcing of \t{REQUIRED_USE}, the package manager can attempt to
resolve unmet USE state
+constraints through automatically adjusting the effective USE flags for the
package being built,
+according to the algorithm specified below. Any adjustments done this way must
not affect
+the package version permanently. The package manager must reevaluate the flags
using the original
+user configuration every time the package is being built.
+
+The package flags that are either masked or forced according to the
section~\ref{sec:use-mask-force}
+are considered immutable. The enforcing process must not alter the values of
immutable flags.
+If the \t{REQUIRED_USE} constraint can not be satisfied without altering
immutable flags, automatic
+enforcing fails.
+
+In order to enforce \t{REQUIRED_USE}, the package manager should process every
USE constraint,
+in order of listing, according to the following rules:
+
+\begin{compactitem}
+\item For an unmatched use flag, the package manager should negate the state
of the specified flag
+ in order to make the constraint match.
+\item For an unmatched all-of group, the package manager should recursively
enforce all
+ constraints inside the group, in order of listing.
+\item For an unmatched use-conditonal group, the package manager should
recursively enforce all
+ constraints inside the group, in order of listing. The associated
condition flag is not altered.
+\item For an unmatched any-of group, the package manager should recursively
enforce the first item
+ inside the group that can be enforced without altering immutable flags, in
order of listing.
+\item For an unmatched at-most-one-of group:
+ \begin{compactitem}
+ \item If two or more items match due to immutable flags, the package
manager must report
+ failure.
+ \item If exactly one of the items match due to immutable flags, the
package manager should
+ enforce all other items not to match, according to the rule specified
below.
+ \item If none of the items match due to immutable flags, the package
manager should enforce all
+ items not to match but the first item in order of listing that matches
currently.
+ \end{compactitem}
+\item For an unmatched exactly-one-of group:
+ \begin{compactitem}
+ \item If none of the items match, the package manager should behave as for
unmatched any-of
+ group.
+ \item If more than one item matches, the package manager should behave as
for unmatched
+ at-most-one-of group.
+ \end{compactitem}
+\end{compactitem}
+
+In order to enforce a matched use flag item not to match, the package manager
should negate
+the state of the flag. The method of enforcing any other item type not to
match is undefined.
+
+\ChangeWhenAddingAnEAPI{7}
+\begin{centertable}{EAPIs supporting automatic enforcing of \t{REQUIRED_USE}}
+ \label{tab:enforce-required-use-table}
+ \begin{tabular}{ll}
+ \toprule
+ \multicolumn{1}{c}{\textbf{EAPI}} &
+ \multicolumn{1}{c}{\textbf{Supports enforcing \t{REQUIRED_USE}?}} \\
+ \midrule
+ 0, 1, 2, 3, 4, 5, 6 & No \\
+ 7 & Yes \\
+ \bottomrule
+ \end{tabular}
+\end{centertable}
+
\subsection{Restrict}
\label{sec:restrict}
diff --git a/eapi-differences.tex b/eapi-differences.tex
index a0d1f01..87ce708 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{REQUIRED_USE} autoenforced & \compactfeatureref{auto-req-use} &
+ No & No & No & No & Yes \\
+
\t{die} in subshell & \compactfeatureref{subshell-die} &
No & No & No & No & Yes \\
@@ -463,6 +466,7 @@ EAPI 7 is EAPI 6 with the following changes:
\item \t{nonfatal} defined both as a shell function and external command,
\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}.
\end{compactitem}
\ChangeWhenAddingAnEAPI{7}
diff --git a/profiles.tex b/profiles.tex
index edc17af..46c7928 100644
--- a/profiles.tex
+++ b/profiles.tex
@@ -145,6 +145,7 @@ specification is limited to the forms defined by the
directory's EAPI. In some E
\t{package.use} can be a directory instead of a regular file as per
section~\ref{sec:line-stacking}.
\subsection{USE masking and forcing}
+\label{sec:use-mask-force}
This section covers the eight files \t{use.mask}, \t{use.force},
\t{use.stable.mask},
\t{use.stable.force}, \t{package.use.mask}, \t{package.use.force},
\t{package.use.stable.mask},
and \t{package.use.\allowbreak stable.force}. They are described together
because they interact in
