pkg-mgr-commands.tex: Clarify which commands are allowed in global scope

For most commands this is already implied by the combination of the
statements "When an ebuild is being sourced for metadata querying
rather than for a build [...], no external command may be executed."
in chapter 12 ("Available Commands") and "Except where otherwise
noted, they may be internal [...] or external commands available in
PATH; where this is not specified, ebuilds may not rely upon either
behaviour." in section 12.3 ("Ebuild-specific Commands").

For output commands (einfo etc.) and debug commands (debug-print etc.)
to be allowed in global scope, they must be implemented as shell
functions. Specify this, which follows the implementation in all three
package managers.

Closes: https://bugs.gentoo.org/520528
Signed-off-by: Ulrich Müller <ulm@gentoo.org>

1 files changed, 12 insertions, 8 deletions

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 331cd33..ebb4b7e 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -4,7 +4,8 @@
 The following commands will always be available in the ebuild environment, provided by the package
 manager. Except where otherwise noted, they may be internal (shell functions or aliases) or external
 commands available in \t{PATH}; where this is not specified, ebuilds may not rely upon either
-behaviour.
+behaviour. Unless otherwise specified, it is an error if an ebuild calls any of these commands in
+global scope.
 
 Unless otherwise noted, any output of these commands ends with a newline.
 
@@ -142,8 +143,9 @@ are given, \t{-r} is assumed.
 These commands display messages to the user. Unless otherwise stated, the entire argument list is
 used as a message, with backslash-escaped characters interpreted as for the \t{echo -e} command of
 bash, notably \t{\textbackslash t} for a horizontal tab, \t{\textbackslash n} for a new line, and
-\t{\textbackslash\textbackslash} for a literal backslash. Ebuilds must not run any of these commands
-once the current phase function has returned.
+\t{\textbackslash\textbackslash} for a literal backslash. These commands must be implemented
+internally as shell functions and may be called in global scope. Ebuilds must not run any of these
+commands once the current phase function has returned.
 
 \featurelabel{output-no-stdout} Unless otherwise noted, output may be sent to stderr or some other
 appropriate facility. In EAPIs listed in table~\ref{tab:output-commands} as not allowing stdout
@@ -927,8 +929,7 @@ any of these functions from any other phase.
 
 \subsection{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. It is an error if an ebuild calls any
-of these functions in global scope.
+these commands once the current phase function has returned.
 
 Unless otherwise noted, 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
@@ -1016,7 +1017,8 @@ table~\ref{tab:use-list-strictness}.
 \end{centertable}
 
 \subsection{Text list functions}
-These functions check a list of arguments for a particular value.
+These functions check a list of arguments for a particular value. They must be implemented
+internally as shell functions and may be called in global scope.
 \nobreakpar
 \begin{description}
 \item[has] Returns shell true (0) if the first argument (a word) is found in the list of subsequent
@@ -1261,8 +1263,9 @@ has returned.
 \end{algorithm}
 
 \item[get_libdir] \featurelabel{get-libdir} Prints the libdir name obtained according to
-    algorithm~\ref{alg:get-libdir}. Must be implemented internally as a shell function.
-    Only available in EAPIs listed in table~\ref{tab:misc-commands} as supporting \t{get_libdir}.
+    algorithm~\ref{alg:get-libdir}. Must be implemented internally as a shell function and may be
+    called in global scope. Only available in EAPIs listed in table~\ref{tab:misc-commands} as
+    supporting \t{get_libdir}.
 
 \begin{algorithm}
 \caption{\t{get_libdir} logic} \label{alg:get-libdir}
@@ -1300,6 +1303,7 @@ has returned.
 \subsection{Debug commands}
 The following commands are available for debugging. Normally all of these commands should be no ops;
 a package manager may provide a special debug mode where these commands instead do something.
+These commands must be implemented internally as shell functions and may be called in global scope.
 Ebuilds must not run any of these commands once the current phase function has returned.
 
 \begin{description}