* [gentoo-pms] [PATCH] pkg-mgr-commands.tex: Clarify which commands are allowed in global scope
@ 2021-08-31 9:39 99% Ulrich Müller
0 siblings, 0 replies; 1+ results
From: Ulrich Müller @ 2021-08-31 9:39 UTC (permalink / raw
To: gentoo-pms; +Cc: Ulrich Müller
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>
---
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 4431435..7db6ef2 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 whitespace-separated lists for a particular value.
+These functions check whitespace-separated lists 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}
--
2.33.0
^ permalink raw reply related [relevance 99%]
Results 1-1 of 1 | reverse | options above
-- pct% links below jump to the message on this page, permalinks otherwise --
2021-08-31 9:39 99% [gentoo-pms] [PATCH] pkg-mgr-commands.tex: Clarify which commands are allowed in global scope Ulrich Müller
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox