[gentoo-pms] [PATCH v2 1/2] Clarify use of the terms "export" and "environment variable"

[gentoo-pms] [PATCH v2 1/2] Clarify use of the terms "export" and "environment variable"

[Ulrich Müller]

Signed-off-by: Ulrich Müller <ulm@gentoo.org>
---
 ebuild-env-vars.tex  |  6 +++---
 ebuild-functions.tex | 22 +++++++++++-----------
 ebuild-vars.tex      |  4 ++--
 3 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex
index 0fcf457..871a0d2 100644
--- a/ebuild-env-vars.tex
+++ b/ebuild-env-vars.tex
@@ -211,14 +211,14 @@ inconsistent variable.
     No &
     \featurelabel{desttree} Controls the location where \t{dobin}, \t{dolib}, \t{domo},
     and \t{dosbin} install things. Only for EAPIs listed in table~\ref{tab:removed-env-vars-table}
-    as supporting \t{DESTTREE}. In all other EAPIs, this is retained as a conceptual variable not
-    exported to the ebuild environment. \\
+    as supporting \t{DESTTREE}. In all other EAPIs, this is retained as a conceptual variable
+    inaccessible from the ebuild environment. \\
 \t{INSDESTTREE} &
     \t{src_install} &
     No &
     \featurelabel{insdesttree} Controls the location where \t{doins} installs things. Only for EAPIs
     listed in table~\ref{tab:removed-env-vars-table} as supporting \t{INSDESTTREE}. In all other
-    EAPIs, this is retained as a conceptual variable not exported to the ebuild environment. \\
+    EAPIs, this is retained as a conceptual variable inaccessible from the ebuild environment. \\
 \t{USE} &
     All &
     Yes &
diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index 046a0a7..bf6b774 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -8,10 +8,10 @@ by the package manager as part of the build and/or install process. In all cases
 must provide a default implementation of these functions; unless otherwise stated this must be a
 no-op. All functions may assume that they have read access to all system libraries, binaries and
 configuration files that are accessible to normal users, as well as write access to the temporary
-directories specified by the \t{T}, \t{TMPDIR} and \t{HOME} environment variables
+directories specified by the \t{T}, \t{TMPDIR} and \t{HOME} variables
 (see section~\ref{sec:ebuild-env-vars}). Most functions must assume only that they have additional
-write access to the package's working directory (the \t{WORKDIR} environment variable); exceptions
-are noted below.
+write access to the package's working directory (the \t{WORKDIR} variable); exceptions are noted
+below.
 
 The environment for functions run outside of the build sequence (that is, \t{pkg_config},
 \t{pkg_info}, \t{pkg_prerm} and \t{pkg_postrm}) must be the environment used for the build of the
@@ -400,37 +400,37 @@ src_install() {
 
 The \t{pkg_preinst} function performs any special tasks that are required immediately before
 merging the package to the live filesystem. It must not write outside of the directories specified
-by the \t{ROOT} and \t{D} environment variables.
+by the \t{ROOT} and \t{D} variables.
 
 \t{pkg_preinst} must be run with full access to all files and directories below that specified by
-the \t{ROOT} and \t{D} environment variables.
+the \t{ROOT} and \t{D} variables.
 
 \subsection{pkg_postinst}
 
 The \t{pkg_postinst} function performs any special tasks that are required immediately after
 merging the package to the live filesystem. It must not write outside of the directory specified
-in the \t{ROOT} environment variable.
+in the \t{ROOT} variable.
 
 \t{pkg_postinst}, like, \t{pkg_preinst}, must be run with full access to all files and directories
-below that specified by the \t{ROOT} environment variable.
+below that specified by the \t{ROOT} variable.
 
 \subsection{pkg_prerm}
 
 The \t{pkg_prerm} function performs any special tasks that are required immediately before
 unmerging the package from the live filesystem. It must not write outside of the directory specified
-by the \t{ROOT} environment variable.
+by the \t{ROOT} variable.
 
 \t{pkg_prerm} must be run with full access to all files and directories below that specified by
-the \t{ROOT} environment variable.
+the \t{ROOT} variable.
 
 \subsection{pkg_postrm}
 
 The \t{pkg_postrm} function performs any special tasks that are required immediately after
 unmerging the package from the live filesystem. It must not write outside of the directory specified
-by the \t{ROOT} environment variable.
+by the \t{ROOT} variable.
 
 \t{pkg_postrm} must be run with full access to all files and directories below that specified by
-the \t{ROOT} environment variable.
+the \t{ROOT} variable.
 
 \subsection{pkg_config}
 
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 561eb0c..b030943 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -305,8 +305,8 @@ considered to be part of the ebuild's metadata:
 \note{Thus, by extension of section~\ref{sec:metadata-invariance}, \t{inherit} may not be used
 conditionally, except upon constant conditions.}
 
-The following are special variables defined by the package manager for internal use and may or may
-not be exported to the ebuild environment:
+The following is a special variable defined by the package manager for internal use and may or may
+not be available in the ebuild environment:
 
 \begin{description}
 \item[DEFINED_PHASES] \featurelabel{defined-phases} A space separated arbitrarily ordered list
-- 
2.47.1

[gentoo-pms] [PATCH v2 2/2] EAPI 9: Defined variables are no longer exported

[Ulrich Müller]

Bug: https://bugs.gentoo.org/721088
Signed-off-by: Ulrich Müller <ulm@gentoo.org>
---
 eapi-differences.tex |  4 ++++
 ebuild-env-vars.tex  | 36 +++++++++++++++++++++++++++++-------
 ebuild-vars.tex      |  4 ++++
 3 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/eapi-differences.tex b/eapi-differences.tex
index c8f8a44..1fd03a0 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -69,6 +69,9 @@ Accumulate \t{PROPERTIES} & \compactfeatureref{accumulate-vars} &
 Accumulate \t{RESTRICT} & \compactfeatureref{accumulate-vars} &
     No & No & Yes & Yes \\
 
+Export variables & \compactfeatureref{export-vars} &
+    Yes & Yes & Yes & No \\
+
 \t{PORTDIR} & \compactfeatureref{portdir} &
     Yes & No & No & No \\
 
@@ -365,6 +368,7 @@ EAPI 9 is EAPI 8 with the following changes:
 
 \begin{compactitem}
 \item Different default EAPI for profiles, \featureref{profile-eapi-default}.
+\item Defined variables no longer exported, \featureref{export-vars}.
 \item \t{assert} banned, \featureref{banned-commands}.
 \item \t{pipestatus}, \featureref{pipestatus}.
 \item Absolute symlinks no longer rewritten, \featureref{symlink-rewrite}.
diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex
index 871a0d2..14ef7bc 100644
--- a/ebuild-env-vars.tex
+++ b/ebuild-env-vars.tex
@@ -1,10 +1,10 @@
 \section{Defined variables}
 \label{sec:ebuild-env-vars}
 
-The package manager must define the following environment variables. Not all variables are
-universally meaningful; variables that are not meaningful in a given phase or in global scope may
-be unset or set to any value. Ebuilds must not attempt to modify any of these variables, unless
-otherwise specified.
+The package manager must define the following variables. Not all variables are universally
+meaningful; variables that are not meaningful in a given phase or in global scope may be unset
+or set to any value. Ebuilds must not attempt to modify any of these variables, unless otherwise
+specified.
 
 Because of their special meanings, these variables may not be preserved consistently across all
 phases as would normally happen due to environment saving (see section~\ref{sec:ebuild-env-state}).
@@ -12,6 +12,26 @@ For example, \t{EBUILD_PHASE} is different for every phase, and \t{ROOT} may hav
 the various different \t{pkg_*} phases. Ebuilds must recalculate any variable they derive from an
 inconsistent variable.
 
+\featurelabel{export-vars} These variables are either exported to the environment or kept as
+unexported shell variables, as specified for EAPIs in table~\ref{tab:export-vars}; exceptions are
+\t{TMPDIR} and \t{HOME} which are always exported to the environment. In EAPIs where variables are
+not exported, the package manager must pass those that are required by ebuild-specific external
+commands (see section~\ref{sec:pkg-mgr-commands}) in an implementation-defined manner.
+
+\ChangeWhenAddingAnEAPI{9}
+\begin{centertable}{EAPIs with variables exported to the environment}
+    \label{tab:export-vars}
+    \begin{tabular}{ll}
+      \toprule
+      \multicolumn{1}{c}{\textbf{EAPI}} &
+      \multicolumn{1}{c}{\textbf{Variables exported?}} \\
+      \midrule
+      0, 1, 2, 3, 4, 5, 6, 7, 8 & Yes \\
+      9                         & No  \\
+      \bottomrule
+    \end{tabular}
+\end{centertable}
+
 \begin{landscape}
 % Reduce width of text area to make room for margin notes
 \addtolength{\hsize}{-25mm}
@@ -168,13 +188,15 @@ inconsistent variable.
 \t{TMPDIR} &
     All &
     Partially\footnotemark[\value{footnote}] &
-    Must be set to the location of a usable temporary directory, for any applications
-    called by an ebuild. Must not be used by ebuilds directly; see \t{T} above. \\
+    Must be set to the location of a usable temporary directory, for any applications called
+    by an ebuild. Must not be used by ebuilds directly; see \t{T} above. \t{TMPDIR} is always
+    exported to the environment. \\
 \t{HOME} &
     All &
     Partially\footnotemark[\value{footnote}] &
     The full path to an appropriate temporary directory for use by any programs invoked by the
-    ebuild that may read or modify the home directory. \\
+    ebuild that may read or modify the home directory. \t{HOME} is always exported to the
+    environment. \\
 \t{EPREFIX} &
     All &
     Yes &
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index b030943..9979ce9 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -335,6 +335,10 @@ defined based upon any variant condition.}
     \end{tabular}
 \end{centertable}
 
+For EAPIs listed in table~\ref{tab:export-vars} with the property that variables are not exported,
+the package manager must not export any of the variables specified in this section to the
+environment.
+
 % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
 
 %%% Local Variables:
-- 
2.47.1