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

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

[Ulrich Müller]

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

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 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 0fcf457..4c357fd 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 shell's 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 shell's 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 shell's
+    environment. \\
 \t{EPREFIX} &
     All &
     Yes &
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index b030943..a1b0010 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 shell's
+environment.
+
 % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
 
 %%% Local Variables:
-- 
2.47.1