From 314305e14f9f412c11369a655eb1a61a5b2c6001 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@gentoo.org>
Date: Sun, 23 May 2021 11:45:56 +0200
Subject: [PATCH] EAPI 8 has an empty working directory in pkg_* phases
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

https://bugs.gentoo.org/595030
Signed-off-by: Ulrich Müller <ulm@gentoo.org>
---
 eapi-differences.tex |  4 ++++
 ebuild-functions.tex | 26 +++++++++++++++++++++-----
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/eapi-differences.tex b/eapi-differences.tex
index f3af563..08c4e9f 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -111,6 +111,9 @@ Use dependencies & \compactfeatureref{use-deps} &
 \t{!!}\ blockers & \compactfeatureref{bang-strength} &
     * & Strong & Strong & Strong & Strong \\
 
+Working directory in \t{pkg_*} phases & \compactfeatureref{phase-function-dir} &
+    Any & Any & Any & Any & Empty \\
+
 \t{S} to \t{WORKDIR} fallback & \compactfeatureref{s-workdir-fallback} &
     * & Conditional & Conditional & Conditional & Conditional \\
 
@@ -494,6 +497,7 @@ EAPI 8 is EAPI 7 with the following changes:
 \item Bash version is 5.0, \featureref{bash-version}.
 \item Selective fetch/mirror restriction, \featureref{uri-restrict}.
 \item \t{IDEPEND}, \featureref{idepend}.
+\item Empty working directory in \t{pkg_*} phase functions, \featureref{phase-function-dir}.
 \end{compactitem}
 
 \ChangeWhenAddingAnEAPI{8}
diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index ffdea16..00fd259 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -22,11 +22,13 @@ Ebuilds must not call nor assume the existence of any phase functions.
 \subsection{Initial working directories}
 \label{sec:s-to-workdir-fallback}
 
-Some functions may assume that their initial working directory is set to a particular location;
-these are noted below. If no initial working directory is mandated, it may be set to anything and
-the ebuild must not rely upon a particular location for it. The ebuild \emph{may} assume that the
-initial working directory for any phase is a trusted location that may only be written to by a
-privileged user and group.
+\featurelabel{phase-function-dir} Some functions may assume that their initial working directory is
+set to a particular location; these are noted below. If no initial working directory is mandated,
+then for EAPIs listed in table~\ref{tab:function-dirs} as having an empty directory, it must be set
+to a dedicated directory that is empty at the start of the function and may be read-only. For other
+EAPIs, it may be set to anything. The ebuild must not rely upon a particular location for it.
+The ebuild \emph{may} assume that the initial working directory for any phase is a trusted location
+that may only be written to by a privileged user and group.
 
 \featurelabel{s-workdir-fallback} Some functions are described as having an initial working
 directory of \t{S} with an error or fallback to \t{WORKDIR}\@. For EAPIs listed in
@@ -44,6 +46,20 @@ fallback to \t{WORKDIR} is used:
     executed, are in \t{DEFINED_PHASES}.
 \end{compactitem}
 
+\ChangeWhenAddingAnEAPI{8}
+\begin{centertable}{Initial working directory in \t{pkg_*} phase functions for EAPIs}
+    \label{tab:function-dirs}
+    \begin{tabular}{ll}
+      \toprule
+      \multicolumn{1}{c}{\textbf{EAPI}} &
+      \multicolumn{1}{c}{\textbf{Initial working directory?}} \\
+      \midrule
+      0, 1, 2, 3, 4, 5, 6, 7  & Any   \\
+      8                       & Empty \\
+      \bottomrule
+    \end{tabular}
+\end{centertable}
+
 \ChangeWhenAddingAnEAPI{8}
 \begin{centertable}{EAPIs with \t{S} to \t{WORKDIR} fallbacks}
     \label{tab:s-fallback-table}
-- 
2.31.1