commit: 1c9f1a26ca761f715d7e70d223b896b8a6eeddee Author: Michał Górny <mgorny <AT> gentoo <DOT> org> AuthorDate: Wed Oct 4 17:35:57 2017 +0000 Commit: Michał Górny <mgorny <AT> gentoo <DOT> org> CommitDate: Wed Oct 4 17:36:09 2017 +0000 URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=1c9f1a26
EAPI 7 supports runtime-modifiable USE flags. 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
