diff options
| -rw-r--r-- | dependencies.tex | 15 | ||||
| -rw-r--r-- | eapi-differences.tex | 4 | ||||
| -rw-r--r-- | ebuild-env-vars.tex | 66 | ||||
| -rw-r--r-- | ebuild-vars.tex | 7 | ||||
| -rw-r--r-- | names.tex | 2 | ||||
| -rw-r--r-- | pkg-mgr-commands.tex | 60 | ||||
| -rw-r--r-- | profile-variables.tex | 81 |
7 files changed, 187 insertions, 48 deletions
diff --git a/dependencies.tex b/dependencies.tex index ef1132b..8da2c86 100644 --- a/dependencies.tex +++ b/dependencies.tex @@ -133,6 +133,9 @@ In an all-of group, all of the child elements must be matched. In a use-conditional group, if the associated use flag is enabled (or disabled if it has an 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}. + \subsection{Any-of Dependency Specifications} Any use-conditional group that is an immediate child of an any-of group, if not enabled (disabled @@ -426,8 +429,8 @@ is only for package manager use and must not be used by ebuilds. When multiple use dependencies are specified, all must match for a successful match. It is an error for a use dependency to be applied to an ebuild which does not have the flag in - question in \t{IUSE}, or for an ebuild to use a conditional use dependency when that ebuild does - not have the flag in \t{IUSE}. + question in \t{IUSE\_REFERENCEABLE}, or for an ebuild to use a conditional use dependency when + that ebuild does not have the flag in \t{IUSE\_EFFECTIVE}. }{ } @@ -455,18 +458,18 @@ When multiple requirements are specified, all must match for a successful match. In a 3-style use dependency, the flag name may immediately be followed by a \e{default} specified by either \t{(+)} or \t{(-)}. The former indicates that, when applying the use dependency to a package -that does not have the flag in question in \t{IUSE}, the package manager shall behave as if the flag -were present and enabled; the latter, present and disabled. +that does not have the flag in question in \t{IUSE\_REFERENCEABLE}, the package manager shall behave +as if the flag were present and enabled; the latter, present and disabled. Unless a 3-style default is specified, it is an error for a use dependency to be applied to an -ebuild which does not have the flag in question in \t{IUSE}. +ebuild which does not have the flag in question in \t{IUSE\_REFERENCEABLE}. \note By extension of the above, a default that could reference an ebuild using an EAPI not supporting profile \t{IUSE} injections cannot rely upon any particular behaviour for flags that 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}. +flag in \t{IUSE\_EFFECTIVE}. \IFKDEBUILDELSE { diff --git a/eapi-differences.tex b/eapi-differences.tex index 05269d9..93e609a 100644 --- a/eapi-differences.tex +++ b/eapi-differences.tex @@ -56,6 +56,9 @@ \IFKDEBUILDCOLOUR{\t{.ebuild}} \\ }{} +Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No & No & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ + \t{IUSE} defaults & table~\ref{tab:iuse-defaults-table} & No & Yes & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes & Yes \\ @@ -300,6 +303,7 @@ EAPI 3 is EAPI 2 with the following changes: \item \t{unpack} supports \t{.xz} and \t{.tar.xz}, table~\ref{tab:unpack-extensions-table}. \item \t{econf} adds \t{-{}-disable-dependency-tracking}, table~\ref{tab:econf-options-table}. \item \t{pkg\_info} can run on non-installed packages, table~\ref{tab:pkg-info-table}. +\item \t{USE} is calculated differently, table~\ref{tab:profile-iuse-injection-table}. \end{compactitem} % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex index 0aacb84..8b36002 100644 --- a/ebuild-env-vars.tex +++ b/ebuild-env-vars.tex @@ -139,8 +139,8 @@ variable. \t{USE} & All & Yes & - A whitespace-delimited list of all active USE flags for this ebuild, including those - originating from variables in \t{USE\_EXPAND}. \\ + A whitespace-delimited list of all active USE flags for this ebuild. See + section~\ref{sec:use-iuse-handling} for details. \\ \t{EBUILD\_PHASE} & All & No & @@ -173,6 +173,68 @@ package manager specific directories. \t{GZIP}, \t{BZIP}, \t{BZIP2}, \t{CDPATH}, \t{GREP\_OPTIONS}, \t{GREP\_COLOR} and \t{GLOBIGNORE} must not be set. +\subsection{USE and IUSE Handling} +\label{sec:use-iuse-handling} + +This section discusses the handling of four variables: + +\begin{description} +\item[IUSE] is the variable calculated from the \t{IUSE} 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 + packages about an ebuild's state (for example, for use dependencies). +\item[IUSE\_EFFECTIVE] is another conceptual, unexported variable. Values in \t{IUSE\_EFFECTIVE} are + those which an ebuild may legally use in queries about itself (for example, for the \t{use} + function, and for use in dependency specification conditional blocks). +\item[USE] is a variable calculated by the package manager and exported to the ebuild environment. +\end{description} + +For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as not supporting profile defined +\t{IUSE} injection, \t{IUSE\_REFERENCEABLE} is equal to the calculated \t{IUSE} value. For EAPIs +where profile defined \t{IUSE} injection is supported, \t{IUSE\_REFERENCEABLE} is equal to +\t{IUSE\_EFFECTIVE}. + +For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as not supporting profile defined +\t{IUSE} injection, \t{IUSE\_EFFECTIVE} contains the following values: + +\begin{compactitem} +\item All values in the calculated \t{IUSE} value. +\item All possible values for the \t{ARCH} variable. +\item All legal use flag names whose name starts with the lowercase equivalent of any value in + the profile \t{USE\_EXPAND} variable followed by an underscore. +\end{compactitem} + +For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as supporting profile defined \t{IUSE} +injection, \t{IUSE\_EFFECTIVE} contains the following values: + +\begin{compactitem} +\item All values in the calculated \t{IUSE} value. +\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 + \t{USE\_EXPAND\_IMPLICIT} variables. +\item All values for \t{\$\{lower\_v\}\_\$\{x\}}, where \t{\$\{x\}} is 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} and \t{USE\_EXPAND\_IMPLICIT} variables and + \t{\$\{lower\_v\}} is the lowercase equivalent of \t{\$\{v\}}. +\end{compactitem} + +The \t{USE} variable is set by the package manager. For each value in \t{IUSE\_EFFECTIVE}, \t{USE} +shall contain that value if the flag is to be enabled for the ebuild in question, and shall not +contain that value if it is to be disabled. In EAPIs listed in +table~\ref{tab:profile-iuse-injection-table} as not supporting profile defined \t{IUSE} injection, +\t{USE} may contain other flag names that are not relevant for the ebuild. + +For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as supporting profile defined +\t{IUSE} injection, the variables named in \t{USE\_EXPAND} and \t{USE\_EXPAND\_UNPREFIXED} shall +have their profile-provided values reduced to contain only those values that are present in +\t{IUSE\_EFFECTIVE}. + +For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as supporting profile defined +\t{IUSE} injection, the package manager must save the calculated value of \t{IUSE\_EFFECTIVE} when +installing a package. Details are beyond the scope of this specification. + % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : %%% Local Variables: diff --git a/ebuild-vars.tex b/ebuild-vars.tex index bf7a8c8..d00b01f 100644 --- a/ebuild-vars.tex +++ b/ebuild-vars.tex @@ -25,11 +25,10 @@ All ebuilds must define at least the following variables: eclass. Must not be empty. \item[HOMEPAGE] The URI or URIs for a package's homepage, including protocols. May be defined by an eclass. See section~\ref{sec:dependencies} for full syntax. -\item[IUSE] The \t{USE} flags used by the ebuild. Historically, \t{USE\_EXPAND} values and \t{ARCH} - were not included; package managers should support this for backwards compatibility reasons. Ebuilds - must list only flags used by the ebuild itself. Any eclass that works with \t{USE} flags +\item[IUSE] The \t{USE} flags used by the ebuild. Any eclass that works with \t{USE} flags must also set \t{IUSE}, listing only the variables used by that eclass. The package manager is - responsible for merging these values. + responsible for merging these values. See section~\ref{sec:use-iuse-handling} for discussion on + which values must be listed this variable. In EAPIs shown in table~\ref{tab:iuse-defaults-table} as supporting \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 @@ -27,7 +27,7 @@ hyphen or a dot. \subsection{USE Flag Names} A USE flag name may contain any of the characters [\t{A-Za-z0-9+\_@-}]. It must begin with an alphanumeric character. Underscores should be considered reserved for \t{USE\_EXPAND}, as -described in section~\ref{use-expand}. +described in section~\ref{sec:use-iuse-handling}. \note The at-sign is required for \t{LINGUAS}. diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex index 174d11d..9f005ad 100644 --- a/pkg-mgr-commands.tex +++ b/pkg-mgr-commands.tex @@ -583,12 +583,13 @@ in table~\ref{tab:compression-table} as supporting \t{docompress}. } \end{centertable} -\subsubsection{List Functions} -These functions work on variables containing whitespace-delimited lists (e.g. \t{USE}). Ebuilds must -not run any of these commands once the current phase function has returned. Ebuilds must not call -any function that operates upon \t{USE} to query a value that is not either listed in \t{IUSE}, a -\t{USE\_EXPAND} value or an \t{ARCH} value; package manager behaviour is undefined if such a call -is made. +\subsubsection{Use List Functions} +These functions provide behaviour based upon set or unset use flags. Ebuilds must not run any of +these commands once the current phase function has returned. Ebuilds must not run any of these +functions in global scope. + +If any of these functions is called with a flag value that is not included in \t{IUSE\_EFFECTIVE}, +either behaviour is undefined or it is an error as decided by table~\ref{tab:use-list-strictness}. \begin{description} \item[use] Returns shell true (0) if the first argument (a \t{USE} flag name) is enabled, false @@ -596,22 +597,55 @@ is made. false if it is enabled. It is guaranteed that this command is quiet. \item[usev] The same as \t{use}, but also prints the flag name if it is enabled. \item[useq] Deprecated synonym for \t{use}. -\\ -\item[has] Returns shell true (0) if the first argument (a word) is found in the list of subsequent - arguments, false otherwise. Guaranteed quiet. -\item[hasv] The same as \t{has}, but also prints the first argument if found. -\item[hasq] Deprecated synonym for \t{has}. -\\ \item[use\_with] Has one-, two-, and three-argument forms. The first argument is a USE flag name, the second a \t{configure} option name (\t{\$\{opt\}}), defaulting to the same as the first argument if not provided, and the third is a string value (\t{\$\{value\}}), defaulting to nothing. If the USE flag is set, outputs \t{-{}-with-\$\{opt\}=\$\{value\}} if the third argument was provided, and \t{-{}-with-\$\{opt\}} otherwise. If the flag is not set, then it outputs \t{-{}-without-\$\{opt\}}. - \item[use\_enable] Works the same as \t{use\_with()}, but outputs \t{-{}-enable-} or \t{-{}-disable-} instead of \t{-{}-with-} or \t{-{}-without-}. \end{description} +\begin{centertable}{EAPI Behaviour for Use Queries not in IUSE\_EFFECTIVE} \label{tab:use-list-strictness} +\IFKDEBUILDELSE +{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Behaviour}} \\ + \midrule + \t{0} & Undefined \\ + \t{1} & Undefined \\ + \t{kdebuild-1} & Undefined \\ + \t{2} & Undefined \\ + \t{3} & Error \\ + \bottomrule + \end{tabular} +}{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Behaviour}} \\ + \midrule + \t{0} & Undefined \\ + \t{1} & Undefined \\ + \t{2} & Undefined \\ + \t{3} & Error \\ + \bottomrule + \end{tabular} +} +\end{centertable} + +\subsubsection{Text List Functions} +These functions check whitespace-separated lists for a particular value. + +\begin{description} +\item[has] Returns shell true (0) if the first argument (a word) is found in the list of subsequent + arguments, false otherwise. Guaranteed quiet. +\item[hasv] The same as \t{has}, but also prints the first argument if found. +\item[hasq] Deprecated synonym for \t{has}. +\end{description} + \subsubsection{Misc Commands} The following commands are always available in the ebuild environment, but don't really fit in any of the above categories. Ebuilds must not run any of these commands once the current phase function diff --git a/profile-variables.tex b/profile-variables.tex index cebcd68..eb453e1 100644 --- a/profile-variables.tex +++ b/profile-variables.tex @@ -21,41 +21,78 @@ variables must be treated in this fashion: \item Any variable whose name is listed in \t{USE\_EXPAND} \end{compactitem} +If the package manager supports any EAPI listed in table~\ref{tab:profile-iuse-injection-table} as +using profile-defined \t{IUSE} injection, the following variables must also be treated +incrementally; otherwise, the following variables may or may not be treated incrementally: +\begin{compactitem} +\item \t{IUSE\_IMPLICIT} +\item \t{USE\_EXPAND\_IMPLICIT} +\item Any variable whose name is \t{USE\_EXPAND\_VALUES\_\$\{value\}}, where \t{\$\{value\}} is any + value in \t{USE\_EXPAND\_IMPLICIT}. +\end{compactitem} + Other variables, except where they affect only package-manager-specific functionality (such as Portage's \t{FEATURES} variable), must not be treated incrementally---later definitions shall completely override those in parent profiles. +\begin{centertable}{Profile-defined \t{IUSE} injection for EAPIs} \label{tab:profile-iuse-injection-table} +\IFKDEBUILDELSE +{ + \begin{tabular}{ l l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports profile-defined \t{IUSE} injection?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & No \\ + \t{2} & No \\ + \t{3} & Yes \\ + \bottomrule + \end{tabular} +}{ + \begin{tabular}{ l l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports profile-defined \t{IUSE} injection?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & No \\ + \t{3} & Yes \\ + \bottomrule + \end{tabular} +} +\end{centertable} + \subsection{Specific variables and their meanings} The following variables have specific meanings when set in profiles. \begin{description} -\item[ARCH] The system's architecture. Must be a value listed in - \t{profiles/arch.list}; see section~\ref{arch.list} - for more information. Must be equal to the primary \t{KEYWORD} for this - profile. +\item[ARCH] The system's architecture. Must be a value listed in \t{profiles/arch.list}; see + section~\ref{arch.list} for more information. Must be equal to the primary \t{KEYWORD} for this + profile. \item[CONFIG\_PROTECT, CONFIG\_PROTECT\_MASK] Contain whitespace-delimited lists used to control the configuration file protection. Described more fully in chapter~\ref{sec:config-protect}. \item[USE] Defines the list of default USE flags for this profile. Flags may be added or removed by the user's configuration. \t{USE\_EXPAND} values must not be specified in this way. -\item[USE\_EXPAND] \label{use-expand} Defines a list of variables which are to be treated - incrementally and whose contents are to be expanded into the USE variable as passed to ebuilds. - Expansion is done as per Algorithm~\ref{alg:use-expand}. - \begin{algorithm} - \caption{USE\_EXPAND logic} \label{alg:use-expand} - \begin{algorithmic} - \FOR{each variable $V$ listed in \t{USE\_EXPAND}} - \FOR{each token $T$ in $V$} - \STATE append $v$\_$T$ to \t{USE}, where $v$ is the lowercase of $V$ - \ENDFOR - \ENDFOR - \end{algorithmic} - \end{algorithm} - So, for example, if \t{USE\_EXPAND} contains `ALSA\_CARDS', and the \t{ALSA\_CARDS} variable - contains `foo', `alsa\_cards\_foo' will be appended to \t{USE}. -\item[USE\_EXPAND\_HIDDEN] Contains a (possibly empty) subset of names from \t{USE\_EXPAND}. The - package manager may use this set as a hint to avoid displaying uninteresting or unhelpful - information to an end user. +\item[USE\_EXPAND] Defines a list of variables which are to be treated incrementally and whose + contents are to be expanded into the USE variable as passed to ebuilds. See + section~\ref{sec:use-iuse-handling} for details. +\item[USE\_EXPAND\_UNPREFIXED] Similar to \t{USE\_EXPAND}, but no prefix is used. If the repository + contains any package using an EAPI supporting profile-defined \t{IUSE} injection (see + table~\ref{tab:profile-iuse-injection-table}), this list must contain at least \t{ARCH}. See + section~\ref{sec:use-iuse-handling} for details. +\item[USE\_EXPAND\_HIDDEN] Contains a (possibly empty) subset of names from \t{USE\_EXPAND} and + \t{USE\_EXPAND\_UNPREFIXED}. The package manager may use this set as a hint to avoid displaying + uninteresting or unhelpful information to an end user. +\item[USE\_EXPAND\_IMPLICIT, IUSE\_IMPLICIT] Used to inject implicit values into \t{IUSE}. See + section~\ref{sec:use-iuse-handling} for details. \end{description} +In addition, for EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as supporting profile +defined \t{IUSE} injection, the variables named in \t{USE\_EXPAND} and \t{USE\_EXPAND\_UNPREFIXED} +have special handling as described in section~\ref{sec:use-iuse-handling}. + Any other variables set in \t{make.defaults} must be passed on into the ebuild environment as-is, and are not required to be interpreted by the package manager. |