\section{Profile Variables}
\label{sec:profile-variables}

This section documents variables that have special meaning, or special behaviour, when defined in a
profile's \t{make.defaults} file.

\subsection{Incremental variables}
\i{Incremental} variables must stack between parent and child profiles in the following manner:
Beginning with the highest parent profile, tokenise the variable's value based on whitespace and
concatenate the lists. Then, for any token $T$ beginning with a hyphen, remove it and any previous
tokens whose value is equal to $T$ with the hyphen removed, or, if $T$ is equal to \t{-*}, remove
all previous values. Note that because of this treatment, the order of tokens in the final result is
arbitrary, not necessarily related to the order of tokens in any given profile. The following
variables must be treated in this fashion:
\begin{compactitem}
\item \t{USE}
\item \t{USE_EXPAND}
\item \t{USE_EXPAND_HIDDEN}
\item \t{CONFIG_PROTECT}
\item \t{CONFIG_PROTECT_MASK}
\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 \t{USE_EXPAND_UNPREFIXED}
\end{compactitem}

If the package manager supports any EAPI listed in table~\ref{tab:profile-env-unset} as using
\t{ENV_UNSET}, the following variable must also be treated incrementally; otherwise, it may or
may not be treated incrementally:
\begin{compactitem}
\item \t{ENV_UNSET}
\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.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{Profile-defined \t{IUSE} injection for EAPIs}
    \label{tab:profile-iuse-injection-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports profile-defined \t{IUSE} injection?}} \\
      \midrule
      0, 1, 2, 3, 4     & No  \\
      5, 6, 7, 8        & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{Profile-defined unsetting of variables in EAPIs}
    \label{tab:profile-env-unset}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{ENV_UNSET}?}} \\
      \midrule
      0, 1, 2, 3, 4, 5, 6 & No  \\
      7, 8                & 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{sec:profiles-dir} 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 section~\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] 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.
\item[ENV_UNSET] Contains a whitespace-delimited list of variables that the package manager shall
    unset. See section~\ref{sec:ebuild-env-vars} 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.

% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pms"
%%% LaTeX-indent-level: 4
%%% LaTeX-item-indent: 0
%%% TeX-brace-indent-level: 4
%%% fill-column: 100
%%% End: