commit: 153324136107543ef07b1378f08bce81199a9022
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Mon Aug 30 19:32:16 2021 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Aug 31 16:05:50 2021 +0000
URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=15332413
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 <AT> gentoo.org>
pkg-mgr-commands.tex | 20 ++++++++++++--------
1 file 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}
