From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 4A0EE1580B2 for ; Fri, 3 Sep 2021 06:56:10 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 8D486E08C3; Fri, 3 Sep 2021 06:56:09 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 58E73E08C3 for ; Fri, 3 Sep 2021 06:56:09 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 4E46A340FDB for ; Fri, 3 Sep 2021 06:56:08 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id CA5AA82 for ; Fri, 3 Sep 2021 06:56:06 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1630425950.153324136107543ef07b1378f08bce81199a9022.ulm@gentoo> Subject: [gentoo-commits] proj/pms:master commit in: / X-VCS-Repository: proj/pms X-VCS-Files: pkg-mgr-commands.tex X-VCS-Directories: / X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: 153324136107543ef07b1378f08bce81199a9022 X-VCS-Branch: master Date: Fri, 3 Sep 2021 06:56:06 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply X-Archives-Salt: 1cb6cdf7-b70c-462a-a9bb-c983ef811ccb X-Archives-Hash: 1e05dbeb66887331eceb15dfd0811146 commit: 153324136107543ef07b1378f08bce81199a9022 Author: Ulrich Müller gentoo org> AuthorDate: Mon Aug 30 19:32:16 2021 +0000 Commit: Ulrich Müller gentoo 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 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} From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id E2E5715808B for ; Mon, 14 Feb 2022 07:29:50 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 72953E0864; Mon, 14 Feb 2022 07:29:49 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 3B8F4E0864 for ; Mon, 14 Feb 2022 07:29:49 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id 368073431F9 for ; Mon, 14 Feb 2022 07:29:48 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 7E2E22E0 for ; Mon, 14 Feb 2022 07:29:45 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1630425950.153324136107543ef07b1378f08bce81199a9022.ulm@gentoo> Subject: [gentoo-commits] proj/pms:eapi-9 commit in: / X-VCS-Repository: proj/pms X-VCS-Files: pkg-mgr-commands.tex X-VCS-Directories: / X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: 153324136107543ef07b1378f08bce81199a9022 X-VCS-Branch: eapi-9 Date: Mon, 14 Feb 2022 07:29:45 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply X-Archives-Salt: 2d471058-cc4a-46a6-939a-0a60f87468b0 X-Archives-Hash: 9e91f91005a3db1e6e9fc075792478c9 Message-ID: <20220214072945._vJGNcRWgk9HJeOpFOqwFciaAfY3TuBTRyK78Sh3iuQ@z> commit: 153324136107543ef07b1378f08bce81199a9022 Author: Ulrich Müller gentoo org> AuthorDate: Mon Aug 30 19:32:16 2021 +0000 Commit: Ulrich Müller gentoo 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 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}