[gentoo-pms] [PATCH 0/6] Ebuild-specific commands clarification & cleanup

[gentoo-pms] [PATCH 0/6] Ebuild-specific commands clarification & cleanup

[Michał Górny]

Hi,

Here's a short series attempting to clean up and clarify various
installation commands.  Mostly focuses on argument processing but
includes a few other bits I've noticed.  Please review.

--
Best regards,
Michał Górny

Michał Górny (6):
  nonfatal: Reword argument handling to be cleaner
  best_version: Explicitly specify the output format
  Account for 'Build commands' being run in src_test
  *into, *opts: Reword to use 'as ...' wording from 'do*'
  *into, *opts: Clarify the number of arguments
  *into, *opts: Remove redundant offset-prefix sentence from heading

 pkg-mgr-commands.tex | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

-- 
2.17.0

[gentoo-pms] [PATCH 1/6] nonfatal: Reword argument handling to be cleaner

[Michał Górny]

Reword the description of 'nonfatal' to explicitly indicate that it
takes 1+ args and executes them as a command.  The original 'remainder
of its argument' wording sounds weird, given that there is no earlier
mention of argument processing (-> remainder from what?).  This also
clarifies that calling nonfatal with no argument is not valid.
---
 pkg-mgr-commands.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 506673b..cb704f0 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -17,7 +17,7 @@ table~\ref{tab:commands-die-table}.
 
 The following commands affect this behaviour:
 \begin{description}
-\item[nonfatal] \featurelabel{nonfatal} Executes the remainder of its arguments as a command,
+\item[nonfatal] \featurelabel{nonfatal} Takes one or more arguments and executes them as a command,
     preserving the exit status. If this results in a command being called that would normally abort
     the build process due to a failure, instead a non-zero exit status shall be returned. Only in
     EAPIs listed in table~\ref{tab:commands-die-table} as supporting \t{nonfatal}.
-- 
2.17.0

[gentoo-pms] [PATCH 2/6] best_version: Explicitly specify the output format

[Michał Górny]

Explain the format used by best_version command explicitly.  Currently,
the function only lists what gets printed but not in what form or how it
is separated.
---
 pkg-mgr-commands.tex | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index cb704f0..4299624 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -105,8 +105,9 @@ are given, \t{-r} is assumed.
 \item[has_version] Takes exactly one package dependency specification as an argument. Returns
     true if a package matching the specification is installed, and false otherwise.
 \item[best_version] Takes exactly one package dependency specification as an argument. If a
-    matching package is installed, prints the category, package name and version of the highest
-    matching version; otherwise, prints an empty string. The exit code is unspecified.
+    matching package is installed, prints the category, followed by \t{/}, followed by package
+    name, followed by \t{-}, followed by full version of the highest matching version;
+    otherwise, prints an empty string. The exit code is unspecified.
 \end{description}
 
 \ChangeWhenAddingAnEAPI{7}
-- 
2.17.0

Re: [gentoo-pms] [PATCH 2/6] best_version: Explicitly specify the output format

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 1425 bytes --]

>>>>> On Tue, 1 May 2018, Michał Górny wrote:

> Explain the format used by best_version command explicitly.  Currently,
> the function only lists what gets printed but not in what form or how it
> is separated.
> ---
>  pkg-mgr-commands.tex | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)

> diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
> index cb704f0..4299624 100644
> --- a/pkg-mgr-commands.tex
> +++ b/pkg-mgr-commands.tex
> @@ -105,8 +105,9 @@ are given, \t{-r} is assumed.
>  \item[has_version] Takes exactly one package dependency specification as an argument. Returns
>      true if a package matching the specification is installed, and false otherwise.
>  \item[best_version] Takes exactly one package dependency specification as an argument. If a
> -    matching package is installed, prints the category, package name and version of the highest
> -    matching version; otherwise, prints an empty string. The exit code is unspecified.
> +    matching package is installed, prints the category, followed by \t{/}, followed by package
> +    name, followed by \t{-}, followed by full version of the highest matching version;

Do we really need this? I think that "category, package name and
version" is pretty clear.

> +    otherwise, prints an empty string. The exit code is unspecified.
>  \end{description}
 
>  \ChangeWhenAddingAnEAPI{7}
> -- 
> 2.17.0

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: [gentoo-pms] [PATCH 2/6] best_version: Explicitly specify the output format

[Michał Górny]

W dniu wto, 01.05.2018 o godzinie 13∶33 +0200, użytkownik Ulrich Mueller
napisał:
> > > > > > On Tue, 1 May 2018, Michał Górny wrote:
> > Explain the format used by best_version command explicitly.  Currently,
> > the function only lists what gets printed but not in what form or how it
> > is separated.
> > ---
> >  pkg-mgr-commands.tex | 5 +++--
> >  1 file changed, 3 insertions(+), 2 deletions(-)
> > diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
> > index cb704f0..4299624 100644
> > --- a/pkg-mgr-commands.tex
> > +++ b/pkg-mgr-commands.tex
> > @@ -105,8 +105,9 @@ are given, \t{-r} is assumed.
> >  \item[has_version] Takes exactly one package dependency specification as an argument. Returns
> >      true if a package matching the specification is installed, and false otherwise.
> >  \item[best_version] Takes exactly one package dependency specification as an argument. If a
> > -    matching package is installed, prints the category, package name and version of the highest
> > -    matching version; otherwise, prints an empty string. The exit code is unspecified.
> > +    matching package is installed, prints the category, followed by \t{/}, followed by package
> > +    name, followed by \t{-}, followed by full version of the highest matching version;
> 
> Do we really need this? I think that "category, package name and
> version" is pretty clear.
> 

I don't think it's well-specified anywhere.  The current wording would
work as well with the format used by qatom:

  dev-python foo 2


-- 
Best regards,
Michał Górny

Re: [gentoo-pms] [PATCH 2/6] best_version: Explicitly specify the output format

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 787 bytes --]

>>>>> On Tue, 1 May 2018, Ulrich Mueller wrote:

>> -    matching package is installed, prints the category, package name and version of the highest
>> -    matching version; otherwise, prints an empty string. The exit code is unspecified.
>> +    matching package is installed, prints the category, followed by \t{/}, followed by package
>> +    name, followed by \t{-}, followed by full version of the highest matching version;

> Do we really need this? I think that "category, package name and
> version" is pretty clear.

And if we update the wording, I would suggest "the qualified package
name, version, and revision (if any)". This follows the definition
of PF in the variables table.

The term "qualified package name" is explained in section 3.1.2 and in
the glossary.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] [PATCH 3/6] Account for 'Build commands' being run in src_test

[Michał Górny]

---
 pkg-mgr-commands.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 4299624..fa4ad02 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -284,9 +284,9 @@ Ebuilds must not run any of these commands once the current phase function has r
 \end{centertable}
 
 \subsection{Build commands}
-These commands are used during the \t{src_configure}, \t{src_compile}, and \t{src_install}
-phases to run the package's build commands. Ebuilds must not run any of these commands once the
-current phase function has returned.
+These commands are used during the \t{src_configure}, \t{src_compile}, \t{src_test},
+and \t{src_install} phases to run the package's build commands. Ebuilds must not run any of these
+commands once the current phase function has returned.
 
 \begin{description}
 \item[econf] Calls the program's \t{./configure} script. This is designed to work with GNU
-- 
2.17.0

[gentoo-pms] [PATCH 4/6] *into, *opts: Reword to use 'as ...' wording from 'do*'

[Michał Górny]

Reword the *into and *opts commands to use the 'As ..., for ...' wording
used in do*/new* commands.  This makes the descriptions a bit shorter,
and makes it possible to extend the information given in original
commands without having to update the wording of derived commands.
---
 pkg-mgr-commands.tex | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index fa4ad02..6bb06ca 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -722,22 +722,19 @@ has returned.
     if it does not already exist. Failure behaviour is EAPI dependent
     as per section~\ref{sec:failure-behaviour}.
 
-\item[insinto] Sets the value of \t{INSDESTTREE} for future invocations of the above utilities. May
-    create the directory, as specified for \t{into}.
+\item[insinto] As \t{into}, for \t{INSDESTTREE}.
 
-\item[exeinto] Sets the install path for \t{doexe} and \t{newexe}. May create the directory, as specified
-    for \t{into}.
+\item[exeinto] As \t{into}, for install path of \t{doexe} and \t{newexe}.
 
-\item[docinto] Sets the install subdirectory for \t{dodoc} et al. May create the directory, as specified
-    for \t{into}.
+\item[docinto] As \t{into}, for install subdirectory of \t{dodoc} et al.
 
 \item[insopts] Sets the options passed by \t{doins} et al.\ to the \t{install} command.
 
-\item[diropts] Sets the options passed by \t{dodir} et al.\ to the \t{install} command.
+\item[diropts] As \t{insopts}, for \t{dodir} et al.
 
-\item[exeopts] Sets the options passed by \t{doexe} et al.\ to the \t{install} command.
+\item[exeopts] As \t{insopts}, for \t{doexe} et al.
 
-\item[libopts] Sets the options passed by \t{dolib} et al.\ to the \t{install} command.
+\item[libopts] As \t{insopts}, for \t{dolib} et al.
     In EAPIs listed in table~\ref{tab:banned-commands-table}, this command is banned as
     per section~\ref{sec:banned-commands}.
 
-- 
2.17.0

[gentoo-pms] [PATCH 5/6] *into, *opts: Clarify the number of arguments

[Michał Górny]

Clarify the number of arguments taken by *into and *opts.  The former
always takes a single argument, so clarify that calling it without
arguments is invalid.  The latter may take 0+ arguments (with 0
resetting the list), so clarify that the correct way is to pass multiple
arguments rather than a single quoted argument.
---
 pkg-mgr-commands.tex | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 6bb06ca..ad64ad1 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -715,8 +715,9 @@ has returned.
 
 \begin{description}
 
-\item[into] Sets the value of \t{DESTTREE} for future invocations
-    of the above utilities. Creates the directory under \t{\$\{ED\}}
+\item[into] Takes exactly one argument, and sets the value of \t{DESTTREE}
+    for future invocations of the above utilities to it.
+    Creates the directory under \t{\$\{ED\}}
     in offset-prefix aware EAPIs or under \t{\$\{D\}} in offset-prefix
     agnostic EAPIs, using \t{install -d} with no additional options,
     if it does not already exist. Failure behaviour is EAPI dependent
@@ -728,7 +729,9 @@ has returned.
 
 \item[docinto] As \t{into}, for install subdirectory of \t{dodoc} et al.
 
-\item[insopts] Sets the options passed by \t{doins} et al.\ to the \t{install} command.
+\item[insopts] Takes zero or more arguments, and sets the options passed by \t{doins} et al.
+    to the \t{install} command to them. When called with no arguments, resets the option list
+    to empty.
 
 \item[diropts] As \t{insopts}, for \t{dodir} et al.
 
-- 
2.17.0

Re: [gentoo-pms] [PATCH 5/6] *into, *opts: Clarify the number of arguments

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 1802 bytes --]

>>>>> On Tue, 1 May 2018, Michał Górny wrote:

> Clarify the number of arguments taken by *into and *opts.  The former
> always takes a single argument, so clarify that calling it without
> arguments is invalid.  The latter may take 0+ arguments (with 0
> resetting the list), so clarify that the correct way is to pass multiple
> arguments rather than a single quoted argument.
> ---
>  pkg-mgr-commands.tex | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)

> diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
> index 6bb06ca..ad64ad1 100644
> --- a/pkg-mgr-commands.tex
> +++ b/pkg-mgr-commands.tex
> @@ -715,8 +715,9 @@ has returned.
 
>  \begin{description}
 
> -\item[into] Sets the value of \t{DESTTREE} for future invocations
> -    of the above utilities. Creates the directory under \t{\$\{ED\}}
> +\item[into] Takes exactly one argument, and sets the value of \t{DESTTREE}
> +    for future invocations of the above utilities to it.
> +    Creates the directory under \t{\$\{ED\}}

Please rewrap to 100 characters.

>      in offset-prefix aware EAPIs or under \t{\$\{D\}} in offset-prefix
>      agnostic EAPIs, using \t{install -d} with no additional options,
>      if it does not already exist. Failure behaviour is EAPI dependent
> @@ -728,7 +729,9 @@ has returned.
 
>  \item[docinto] As \t{into}, for install subdirectory of \t{dodoc} et al.
 
> -\item[insopts] Sets the options passed by \t{doins} et al.\ to the \t{install} command.
> +\item[insopts] Takes zero or more arguments, and sets the options passed by \t{doins} et al.
> +    to the \t{install} command to them. When called with no arguments, resets the option list
> +    to empty.
 
>  \item[diropts] As \t{insopts}, for \t{dodir} et al.
 
> -- 
> 2.17.0

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] [PATCH 6/6] *into, *opts: Remove redundant offset-prefix sentence from heading

[Michał Górny]

Remove the offset-prefix reference from heading to 'Commands affecting
install destinations'.  The offset-prefix situation is explained
in 'into' already, and it applies only to the *into commands.
---
 pkg-mgr-commands.tex | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index ad64ad1..a9c8b45 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -707,8 +707,7 @@ the current phase function has returned.
 \end{centertable}
 
 \subsection{Commands affecting install destinations}
-The following commands are used to set the various destination trees, all relative to \t{\$\{ED\}} in
-offset-prefix aware EAPIs and relative to \t{\$\{D\}} in offset-prefix agnostic EAPIs, used by the
+The following commands are used to set the various destination trees and options used by the
 above installation commands. They must be shell functions or aliases, due to the need to set variables
 read by the above commands. Ebuilds must not run any of these commands once the current phase function
 has returned.
-- 
2.17.0