[gentoo-pms] [PATCH 27/28] EAPI 7 supports runtime-modifiable USE flags.

[Michał Górny]

Bug: https://bugs.gentoo.org/424283
---
 dependencies.tex     |  3 ++-
 eapi-differences.tex |  4 ++++
 ebuild-env-vars.tex  |  5 ++++-
 ebuild-vars.tex      | 16 ++++++++++++----
 eclasses.tex         | 11 ++++++-----
 metadata-cache.tex   |  1 +
 pkg-mgr-commands.tex |  4 ++++
 7 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/dependencies.tex b/dependencies.tex
index d9592d9..acc447c 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -181,7 +181,8 @@ In a use-conditional group, if the associated use flag is enabled (or disabled i
 exclamation mark prefix), all of the child elements must be matched.
 
 It is an error for a flag to be used if it is not included in \t{IUSE_EFFECTIVE} as described in
-section~\ref{sec:use-iuse-handling}.
+section~\ref{sec:use-iuse-handling}. Flags listed in \t{IUSE_RUNTIME} can be used only
+in \t{RDEPEND}, \t{PDEPEND} and \t{REQUIRED_USE}.
 
 \subsection{Any-of dependency specifications}
 
diff --git a/eapi-differences.tex b/eapi-differences.tex
index a89f5f8..441de70 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{IUSE_RUNTIME} & \compactfeatureref{iuse-runtime} &
+    No & No & No & No & Yes \\
+
 \t{||=} dependency group & \compactfeatureref{binding-leftmost-of} &
     No & No & No & No & Yes \\
 
@@ -471,6 +474,7 @@ EAPI 7 is EAPI 6 with the following changes:
 \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}.
+\item runtime-modifiable USE flags (\t{IUSE_RUNTIME}) are supported, \featureref{iuse-runtime}.
 \end{compactitem}
 
 \ChangeWhenAddingAnEAPI{7}
diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex
index f495014..42bd3a2 100644
--- a/ebuild-env-vars.tex
+++ b/ebuild-env-vars.tex
@@ -355,10 +355,12 @@ table~\ref{tab:locale-settings}.
 \subsection{USE and IUSE handling}
 \label{sec:use-iuse-handling}
 
-This section discusses the handling of four variables:
+This section discusses the handling of five variables:
 
 \begin{description}
 \item[IUSE] is the variable calculated from the \t{IUSE} values defined in ebuilds and eclasses.
+\item[IUSE_RUNTIME] is the variable calculated from the \t{IUSE_RUNTIME} values defined in ebuilds
+    and eclasses.
 \item[IUSE_REFERENCEABLE] is a variable calculated from \t{IUSE} and a variety of other sources
     described below. It is purely a conceptual variable; it is not exported to the ebuild
     environment. Values in \t{IUSE_REFERENCEABLE} may legally be used in queries from other
@@ -392,6 +394,7 @@ as supporting profile defined \t{IUSE} injection, \t{IUSE_EFFECTIVE} contains th
 
 \begin{compactitem}
 \item All values in the calculated \t{IUSE} value.
+\item All values in the calculated \t{IUSE_RUNTIME} value, in EAPIs where this variable is defined.
 \item All values in the profile \t{IUSE_IMPLICIT} variable.
 \item All values in the profile variable named \t{USE_EXPAND_VALUES_\$\{v\}}, where \t{\$\{v\}}
     is any value in the intersection of the profile \t{USE_EXPAND_UNPREFIXED} and
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index e4efcae..17e40ed 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -67,6 +67,12 @@ Ebuilds may define any of the following variables:
     \t{IUSE} defaults, any use flag name in \t{IUSE} may be prefixed by at most one of a plus or a
     minus sign. If such a prefix is present, the package manager may use it as a suggestion as to
     the default value of the use flag if no other configuration overrides it.
+\item[IUSE_RUNTIME] \featurelabel{iuse-runtime} Additional \t{USE} flags used by the ebuild whose
+    values can be altered in place without rebuilding from source. The flags listed
+    in \t{IUSE_RUNTIME} must not alter the package built. They must not be referenced at build time,
+    except for informational purposes. A single flag can not be listed in both \t{IUSE_RUNTIME}
+    and \t{IUSE} simultaneously. Uses the same syntax as \t{IUSE}. Only in EAPIs listed
+    in table~\ref{tab:optional-vars-table} as supporting \t{IUSE_RUNTIME}.
 \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
@@ -103,14 +109,16 @@ Ebuilds may define any of the following variables:
 \ChangeWhenAddingAnEAPI{7}
 \begin{centertable}{EAPIs supporting various ebuild-defined variables}
     \label{tab:optional-vars-table}
-    \begin{tabular}{lll}
+    \begin{tabular}{llll}
       \toprule
       \multicolumn{1}{c}{\textbf{EAPI}} &
       \multicolumn{1}{c}{\textbf{Supports \t{PROPERTIES}?}} &
-      \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED_USE}?}} \\
+      \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED_USE}?}} &
+      \multicolumn{1}{c}{\textbf{Supports \t{IUSE_RUNTIME}?}} \\
       \midrule
-      0, 1, 2, 3        & Optionally & No  \\
-      4, 5, 6, 7        & Yes        & Yes \\
+      0, 1, 2, 3        & Optionally & No  & No  \\
+      4, 5, 6           & Yes        & Yes & No  \\
+      7                 & Yes        & Yes & Yes \\
       \bottomrule
     \end{tabular}
 \end{centertable}
diff --git a/eclasses.tex b/eclasses.tex
index 44683b5..9c2b685 100644
--- a/eclasses.tex
+++ b/eclasses.tex
@@ -34,11 +34,12 @@ The \t{inherit} command must also ensure that:
 
 \section{Eclass-defined Metadata Keys}
 
-The \t{IUSE}, \t{REQUIRED_USE}, \t{DEPEND}, \t{BDEPEND}, \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.
+The \t{IUSE}, \t{IUSE_RUNTIME}, \t{REQUIRED_USE}, \t{DEPEND}, \t{BDEPEND}, \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 df4b8ed..3ec626e 100644
--- a/metadata-cache.tex
+++ b/metadata-cache.tex
@@ -37,6 +37,7 @@ order. Other lines may be present following these; their meanings are not define
     ebuild metadata; see table~\ref{tab:defined-phases-table}.
 \item Build-time dependencies for \t{CBUILD} host (\t{BDEPEND}).
     Blank in some EAPIs; see table~\ref{tab:depend-table}.
+\item Runtime-modifiable use flags that this package respects (\t{IUSE_RUNTIME})
 \item Blank lines to pad the file to 22 lines long
 \end{compactenum}
 
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index af4cd35..eac9bc8 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -808,6 +808,10 @@ Unless otherwise noted, if any of these functions is called with a flag value th
 in \t{IUSE_EFFECTIVE}, either behaviour is undefined or it is an error as decided by
 table~\ref{tab:use-list-strictness}.
 
+In EAPIs listed in table~\ref{tab:optional-vars-table} as supporting \t{IUSE_RUNTIME}, the flags
+listed in \t{IUSE_RUNTIME} can only be referenced in \t{pkg_*} phases. Passing any of those flags
+to one of the following functions during any other phase is an error.
+
 \begin{description}
 \item[use] Returns shell true (0) if the first argument (a \t{USE} flag name) is enabled, false
     otherwise.  If the flag name is prefixed with \t{!}, returns true if the flag is disabled, and
-- 
2.14.2