1 |
For most commands this is already implied by the combination of the |
2 |
statements "When an ebuild is being sourced for metadata querying |
3 |
rather than for a build [...], no external command may be executed." |
4 |
in chapter 12 ("Available Commands") and "Except where otherwise |
5 |
noted, they may be internal [...] or external commands available in |
6 |
PATH; where this is not specified, ebuilds may not rely upon either |
7 |
behaviour." in section 12.3 ("Ebuild-specific Commands"). |
8 |
|
9 |
For output commands (einfo etc.) and debug commands (debug-print etc.) |
10 |
to be allowed in global scope, they must be implemented as shell |
11 |
functions. Specify this, which follows the implementation in all three |
12 |
package managers. |
13 |
|
14 |
Closes: https://bugs.gentoo.org/520528 |
15 |
Signed-off-by: Ulrich Müller <ulm@g.o> |
16 |
--- |
17 |
pkg-mgr-commands.tex | 20 ++++++++++++-------- |
18 |
1 file changed, 12 insertions(+), 8 deletions(-) |
19 |
|
20 |
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex |
21 |
index 4431435..7db6ef2 100644 |
22 |
--- a/pkg-mgr-commands.tex |
23 |
+++ b/pkg-mgr-commands.tex |
24 |
@@ -4,7 +4,8 @@ |
25 |
The following commands will always be available in the ebuild environment, provided by the package |
26 |
manager. Except where otherwise noted, they may be internal (shell functions or aliases) or external |
27 |
commands available in \t{PATH}; where this is not specified, ebuilds may not rely upon either |
28 |
-behaviour. |
29 |
+behaviour. Unless otherwise specified, it is an error if an ebuild calls any of these commands in |
30 |
+global scope. |
31 |
|
32 |
Unless otherwise noted, any output of these commands ends with a newline. |
33 |
|
34 |
@@ -142,8 +143,9 @@ are given, \t{-r} is assumed. |
35 |
These commands display messages to the user. Unless otherwise stated, the entire argument list is |
36 |
used as a message, with backslash-escaped characters interpreted as for the \t{echo -e} command of |
37 |
bash, notably \t{\textbackslash t} for a horizontal tab, \t{\textbackslash n} for a new line, and |
38 |
-\t{\textbackslash\textbackslash} for a literal backslash. Ebuilds must not run any of these commands |
39 |
-once the current phase function has returned. |
40 |
+\t{\textbackslash\textbackslash} for a literal backslash. These commands must be implemented |
41 |
+internally as shell functions and may be called in global scope. Ebuilds must not run any of these |
42 |
+commands once the current phase function has returned. |
43 |
|
44 |
\featurelabel{output-no-stdout} Unless otherwise noted, output may be sent to stderr or some other |
45 |
appropriate facility. In EAPIs listed in table~\ref{tab:output-commands} as not allowing stdout |
46 |
@@ -927,8 +929,7 @@ any of these functions from any other phase. |
47 |
|
48 |
\subsection{USE list functions} |
49 |
These functions provide behaviour based upon set or unset use flags. Ebuilds must not run any of |
50 |
-these commands once the current phase function has returned. It is an error if an ebuild calls any |
51 |
-of these functions in global scope. |
52 |
+these commands once the current phase function has returned. |
53 |
|
54 |
Unless otherwise noted, if any of these functions is called with a flag value that is not included |
55 |
in \t{IUSE_EFFECTIVE}, either behaviour is undefined or it is an error as decided by |
56 |
@@ -1016,7 +1017,8 @@ table~\ref{tab:use-list-strictness}. |
57 |
\end{centertable} |
58 |
|
59 |
\subsection{Text list functions} |
60 |
-These functions check whitespace-separated lists for a particular value. |
61 |
+These functions check whitespace-separated lists for a particular value. They must be implemented |
62 |
+internally as shell functions and may be called in global scope. |
63 |
\nobreakpar |
64 |
\begin{description} |
65 |
\item[has] Returns shell true (0) if the first argument (a word) is found in the list of subsequent |
66 |
@@ -1261,8 +1263,9 @@ has returned. |
67 |
\end{algorithm} |
68 |
|
69 |
\item[get_libdir] \featurelabel{get-libdir} Prints the libdir name obtained according to |
70 |
- algorithm~\ref{alg:get-libdir}. Must be implemented internally as a shell function. |
71 |
- Only available in EAPIs listed in table~\ref{tab:misc-commands} as supporting \t{get_libdir}. |
72 |
+ algorithm~\ref{alg:get-libdir}. Must be implemented internally as a shell function and may be |
73 |
+ called in global scope. Only available in EAPIs listed in table~\ref{tab:misc-commands} as |
74 |
+ supporting \t{get_libdir}. |
75 |
|
76 |
\begin{algorithm} |
77 |
\caption{\t{get_libdir} logic} \label{alg:get-libdir} |
78 |
@@ -1300,6 +1303,7 @@ has returned. |
79 |
\subsection{Debug commands} |
80 |
The following commands are available for debugging. Normally all of these commands should be no ops; |
81 |
a package manager may provide a special debug mode where these commands instead do something. |
82 |
+These commands must be implemented internally as shell functions and may be called in global scope. |
83 |
Ebuilds must not run any of these commands once the current phase function has returned. |
84 |
|
85 |
\begin{description} |
86 |
-- |
87 |
2.33.0 |