[gentoo-pms] [PATCH] Installation commands must be called with at least one parameter.

[gentoo-pms] [PATCH] Installation commands must be called with at least one parameter.

[Ulrich Mueller]

The wording of PMS is somewhat unclear here. However, doins and
friends are implemented in all package managers with a check for at
least one parameter. The patch included below clarifies this.
See also <https://bugs.gentoo.org/show_bug.cgi?id=481664#c15>.

CCing council on this one.

Ulrich


From 24f1da1fec863f1497007985751853c4e7501f50 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@gentoo.org>
Date: Tue, 20 Aug 2013 14:40:41 +0200
Subject: [PATCH] Installation commands must be called with at least one
 parameter.

Also adjust the wording for doinfo, doman, and domo, in order to
clarify that multiple file name parameters are allowed.
---
 pkg-mgr-commands.tex | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index bafa748..bcd254d 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -249,8 +249,9 @@ install} target cannot be used or does not install all needed files. Except wher
 all filenames created or modified are relative to the staging directory including the offset-prefix
 \t{ED} in offset-prefix aware EAPIs, or just the staging directory \t{D} in offset-prefix agnostic
 EAPIs. Existing destination files are overwritten. These commands must all be external programs and
-not bash functions or aliases---that is, they must be callable from \t{xargs}. Ebuilds must not run
-any of these commands once the current phase function has returned.
+not bash functions or aliases---that is, they must be callable from \t{xargs}. Calling any of these
+commands without a parameter is an error. Ebuilds must not run any of these commands once the
+current phase function has returned.
 
 \begin{description}
 \item[dobin] Installs the given files into \t{DESTTREE/bin}, where
@@ -320,8 +321,8 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
     It is undefined whether a failure shall occur if \t{-r} is not specified and a directory is
     encountered. Ebuilds must not rely upon any particular behaviour.
 
-\item[doinfo] Installs a GNU Info file into the \t{/usr/share/info} area with file mode \t{0644}.
-    Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
+\item[doinfo] Installs the given GNU Info files into the \t{/usr/share/info} area with file mode
+    \t{0644}. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[doinitd] Installs the given initscript files into \t{/etc/init.d}, by default with file mode
     \t{0755}. This can be overridden by setting \t{EXEOPTIONS} with the \t{exeopts} function.
@@ -367,9 +368,9 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
 \end{algorithmic}
 \end{algorithm}
 
-\item[doman] Installs a man page into the appropriate subdirectory of \t{/usr/share/man} depending
-    upon its apparent section suffix (e.\,g.\ \t{foo.1} goes to \t{/usr/share/man/man1/foo.1}) with
-    file mode \t{0644}.
+\item[doman] Installs the given man pages into the appropriate subdirectory of \t{/usr/share/man}
+    depending upon its apparent section suffix (e.\,g.\ \t{foo.1} goes to
+    \t{/usr/share/man/man1/foo.1}) with file mode \t{0644}.
 
     \featurelabel{doman-langs} In EAPIs listed in table~\ref{tab:doman-table} as supporting
     language detection by filename, a man page with name of the form \t{foo.}\i{lang}\t{.1} shall
@@ -383,10 +384,10 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
     the empty string. In EAPIs specified by table~\ref{tab:doman-table}, the \t{-i18n} option takes
     precedence over the language code in the filename.
 
-\item[domo] Installs a \t{.mo} file with file mode \t{0644} into the appropriate subdirectory of
-    \t{DESTTREE\slash share\slash locale}, generated by taking the basename of the file, removing
-    the \t{.*} suffix, and appending \t{/LC\_MESSAGES}. The name of the installed files is the
-    package name with \t{.mo} appended. Failure behaviour is EAPI dependent as per
+\item[domo] Installs the given \t{.mo} files with file mode \t{0644} into the appropriate
+    subdirectory of \t{DESTTREE\slash share\slash locale}, generated by taking the basename of the
+    file, removing the \t{.*} suffix, and appending \t{/LC\_MESSAGES}. The name of the installed
+    files is the package name with \t{.mo} appended. Failure behaviour is EAPI dependent as per
     section~\ref{sec:failure-behaviour}.
 
 \item[dosbin] As \t{dobin}, but installs to \t{DESTTREE/sbin}.
-- 
1.8.3.2

[gentoo-pms] Re: [PATCH] Installation commands must be called with at least one parameter.

[Ulrich Mueller]

>>>>> On Tue, 20 Aug 2013, Ulrich Mueller wrote:

> The wording of PMS is somewhat unclear here. However, doins and
> friends are implemented in all package managers with a check for
> at least one parameter. The patch included below clarifies this.
> See also <https://bugs.gentoo.org/show_bug.cgi?id=481664#c15>.

Updated version. Differences to previous patch:
- The introductory paragraph now says "filename parameter" instead
  of "parameter" to account for things like the -r option.
- doins takes "one or more" files as arguments, not "any number"
  of files.

Ulrich


From ec8b2e97b3fbc56d838e0e2982ad2b070f237fd7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@gentoo.org>
Date: Tue, 20 Aug 2013 14:40:41 +0200
Subject: [PATCH] Installation commands must be called with at least one parameter.

Also adjust the wording for doinfo, doman, and domo, in order to
clarify that multiple file name parameters are allowed.
---
 pkg-mgr-commands.tex | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index bafa748..acf71ac 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -249,8 +249,9 @@ install} target cannot be used or does not install all needed files. Except wher
 all filenames created or modified are relative to the staging directory including the offset-prefix
 \t{ED} in offset-prefix aware EAPIs, or just the staging directory \t{D} in offset-prefix agnostic
 EAPIs. Existing destination files are overwritten. These commands must all be external programs and
-not bash functions or aliases---that is, they must be callable from \t{xargs}. Ebuilds must not run
-any of these commands once the current phase function has returned.
+not bash functions or aliases---that is, they must be callable from \t{xargs}. Calling any of these
+commands without a filename parameter is an error. Ebuilds must not run any of these commands once
+the current phase function has returned.
 
 \begin{description}
 \item[dobin] Installs the given files into \t{DESTTREE/bin}, where
@@ -320,14 +321,14 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
     It is undefined whether a failure shall occur if \t{-r} is not specified and a directory is
     encountered. Ebuilds must not rely upon any particular behaviour.
 
-\item[doinfo] Installs a GNU Info file into the \t{/usr/share/info} area with file mode \t{0644}.
-    Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
+\item[doinfo] Installs the given GNU Info files into the \t{/usr/share/info} area with file mode
+    \t{0644}. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[doinitd] Installs the given initscript files into \t{/etc/init.d}, by default with file mode
     \t{0755}. This can be overridden by setting \t{EXEOPTIONS} with the \t{exeopts} function.
     Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}.
 
-\item[doins] \featurelabel{doins} Takes any number of files as arguments and installs them into
+\item[doins] \featurelabel{doins} Takes one or more files as arguments and installs them into
     \t{INSDESTTREE}, by default with file mode \t{0644}. This can be overridden by setting
     \t{INSOPTIONS} with the \t{insopts} function. If the first argument is \t{-r}, then operates
     recursively, descending into any directories given. For EAPIs listed in
@@ -367,9 +368,9 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
 \end{algorithmic}
 \end{algorithm}
 
-\item[doman] Installs a man page into the appropriate subdirectory of \t{/usr/share/man} depending
-    upon its apparent section suffix (e.\,g.\ \t{foo.1} goes to \t{/usr/share/man/man1/foo.1}) with
-    file mode \t{0644}.
+\item[doman] Installs the given man pages into the appropriate subdirectory of \t{/usr/share/man}
+    depending upon its apparent section suffix (e.\,g.\ \t{foo.1} goes to
+    \t{/usr/share/man/man1/foo.1}) with file mode \t{0644}.
 
     \featurelabel{doman-langs} In EAPIs listed in table~\ref{tab:doman-table} as supporting
     language detection by filename, a man page with name of the form \t{foo.}\i{lang}\t{.1} shall
@@ -383,10 +384,10 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
     the empty string. In EAPIs specified by table~\ref{tab:doman-table}, the \t{-i18n} option takes
     precedence over the language code in the filename.
 
-\item[domo] Installs a \t{.mo} file with file mode \t{0644} into the appropriate subdirectory of
-    \t{DESTTREE\slash share\slash locale}, generated by taking the basename of the file, removing
-    the \t{.*} suffix, and appending \t{/LC\_MESSAGES}. The name of the installed files is the
-    package name with \t{.mo} appended. Failure behaviour is EAPI dependent as per
+\item[domo] Installs the given \t{.mo} files with file mode \t{0644} into the appropriate
+    subdirectory of \t{DESTTREE\slash share\slash locale}, generated by taking the basename of the
+    file, removing the \t{.*} suffix, and appending \t{/LC\_MESSAGES}. The name of the installed
+    files is the package name with \t{.mo} appended. Failure behaviour is EAPI dependent as per
     section~\ref{sec:failure-behaviour}.
 
 \item[dosbin] As \t{dobin}, but installs to \t{DESTTREE/sbin}.
-- 
1.8.3.2

[gentoo-pms] [PATCH] src-install-4: Check for empty DOCS variable.

[Ulrich Mueller]

This arises from bug 481664. There seems to be consensus that the
default src_install function of EAPI 4 (and 5) is flawed, because it
cannot handle the case where an ebuild specifies DOCS="" or DOCS=().
The question is whether we wait with a fix until EAPI 6, or if we
change it retroactively.

See https://bugs.gentoo.org/show_bug.cgi?id=481664#c29 and following
(in particular, comment 37) for a discussion of the issue. It looks
like no ebuild is currently affected by this.

Ulrich


From c865af98e08f721383b1ece2a6f310794662d3f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@gentoo.org>
Date: Thu, 22 Aug 2013 12:38:02 +0200
Subject: [PATCH] src-install-4: Check for empty DOCS variable.

---
 ebuild-functions.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index 84847e9..46e6f3b 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -318,9 +318,9 @@ src_install() {
             [[ -s "${d}" ]] && dodoc "${d}"
         done
     elif declare -p DOCS | grep -q "^declare -a " ; then
-        dodoc "${DOCS[@]}"
+        [[ ${DOCS[@]} ]] && dodoc "${DOCS[@]}"
     else
-        dodoc ${DOCS}
+        [[ ${DOCS} ]] && dodoc ${DOCS}
     fi
 }
 \end{verbatim}
-- 
1.8.3.2

[gentoo-pms] Re: [PATCH] src-install-4: Check for empty DOCS variable.

[Ulrich Mueller]

Slightly updated patch, checks for number of array elements which is
cleaner.

Ulrich


From b48d760c84b8dcddb6c39d9448514038d31c84e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@gentoo.org>
Date: Thu, 22 Aug 2013 12:38:02 +0200
Subject: [PATCH] src-install-4: Check for empty DOCS variable.

---
 ebuild-functions.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index 84847e9..5c901ef 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -318,9 +318,9 @@ src_install() {
             [[ -s "${d}" ]] && dodoc "${d}"
         done
     elif declare -p DOCS | grep -q "^declare -a " ; then
-        dodoc "${DOCS[@]}"
+        [[ ${#DOCS[@]} -gt 0 ]] && dodoc "${DOCS[@]}"
     else
-        dodoc ${DOCS}
+        [[ ${DOCS} ]] && dodoc ${DOCS}
     fi
 }
 \end{verbatim}
-- 
1.8.3.2

[gentoo-pms] Re: [PATCH] src-install-4: Check for empty DOCS variable.

[Ulrich Mueller]

>>>>> On Thu, 22 Aug 2013, Ulrich Mueller wrote:

> This arises from bug 481664. There seems to be consensus that the
> default src_install function of EAPI 4 (and 5) is flawed, because it
> cannot handle the case where an ebuild specifies DOCS="" or DOCS=().
> The question is whether we wait with a fix until EAPI 6, or if we
> change it retroactively.

This change was rejected by the council in today's meeting.

Ulrich