GNU bug report logs -
#12715
coreutils-8.20: bad dependency information with man page generation
Previous Next
Reported by: Mike Frysinger <vapier <at> gentoo.org>
Date: Tue, 23 Oct 2012 22:30:01 UTC
Severity: normal
Tags: fixed
Done: Assaf Gordon <assafgordon <at> gmail.com>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 12715 in the body.
You can then email your comments to 12715 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Tue, 23 Oct 2012 22:30:02 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Mike Frysinger <vapier <at> gentoo.org>:
New bug report received and forwarded. Copy sent to
bug-coreutils <at> gnu.org.
(Tue, 23 Oct 2012 22:30:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
if i look at vanilla coreutils-8.20, i see:
Makefile.in:man/uname.1: src/uname.c
which seems to have originated from man/local.mk, but munged:
man/uname.1: src/uname
this causes parallel build problems because man/uname.1 generation can get
scheduled before src/uname has been linked. easy way to reproduce:
./configure
touch src/uname.c
make -j
...
GEN man/uname.1
CC src/hostname.o
CC src/uptime.o
CC src/kill.o
CC src/groups.o
GEN lib/charset.alias
GEN lib/ref-add.sed
GEN lib/ref-del.sed
CC lib/set-mode-acl.o
CC lib/copy-acl.o
CC lib/file-has-acl.o
CC lib/allocator.o
help2man: can't get '--help' info from man/uname.td/uname
CC lib/areadlink.o
make[2]: *** [man/uname.1] Error 127
make[2]: *** Waiting for unfinished jobs....
CC lib/areadlink-with-size.o
-mike
[signature.asc (application/pgp-signature, inline)]
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Tue, 23 Oct 2012 23:51:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 12715 <at> debbugs.gnu.org (full text, mbox):
On 10/23/2012 11:27 PM, Mike Frysinger wrote:
> if i look at vanilla coreutils-8.20, i see:
> Makefile.in:man/uname.1: src/uname.c
>
> which seems to have originated from man/local.mk, but munged:
> man/uname.1: src/uname
>
> this causes parallel build problems because man/uname.1 generation can get
> scheduled before src/uname has been linked. easy way to reproduce:
> ./configure
> touch src/uname.c
> make -j
> ...
> GEN man/uname.1
> CC src/hostname.o
> CC src/uptime.o
> CC src/kill.o
> CC src/groups.o
> GEN lib/charset.alias
> GEN lib/ref-add.sed
> GEN lib/ref-del.sed
> CC lib/set-mode-acl.o
> CC lib/copy-acl.o
> CC lib/file-has-acl.o
> CC lib/allocator.o
> help2man: can't get '--help' info from man/uname.td/uname
> CC lib/areadlink.o
> make[2]: *** [man/uname.1] Error 127
> make[2]: *** Waiting for unfinished jobs....
> CC lib/areadlink-with-size.o
> -mike
Ouch. There was a recent commit related
to that exact issue which should have fixed this?
http://git.sv.gnu.org/gitweb/?p=coreutils.git;a=commit;h=11d6386
The Makefile.in in my local git repo is correct, i.e.
man/uname.1: src/uname
whereas in the dist tarball it's
man/uname.1: src/uname.c
I might get time to investigate some time tomorrow.
thanks,
Pádraig.
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 07:45:01 GMT)
Full text and
rfc822 format available.
Message #11 received at 12715 <at> debbugs.gnu.org (full text, mbox):
Hi Pádraig, Mike.
On 10/24/2012 01:48 AM, Pádraig Brady wrote:
> On 10/23/2012 11:27 PM, Mike Frysinger wrote:
>> if i look at vanilla coreutils-8.20, i see:
>> Makefile.in:man/uname.1: src/uname.c
>>
>> which seems to have originated from man/local.mk, but munged:
>> man/uname.1: src/uname
>>
>> this causes parallel build problems because man/uname.1 generation can get
>> scheduled before src/uname has been linked. easy way to reproduce:
>> ./configure
>> touch src/uname.c
>> make -j
>> ...
>> GEN man/uname.1
>> CC src/hostname.o
>> CC src/uptime.o
>> CC src/kill.o
>> CC src/groups.o
>> GEN lib/charset.alias
>> GEN lib/ref-add.sed
>> GEN lib/ref-del.sed
>> CC lib/set-mode-acl.o
>> CC lib/copy-acl.o
>> CC lib/file-has-acl.o
>> CC lib/allocator.o
>> help2man: can't get '--help' info from man/uname.td/uname
>> CC lib/areadlink.o
>> make[2]: *** [man/uname.1] Error 127
>> make[2]: *** Waiting for unfinished jobs....
>> CC lib/areadlink-with-size.o
>> -mike
>
> Ouch. There was a recent commit related
> to that exact issue which should have fixed this?
> http://git.sv.gnu.org/gitweb/?p=coreutils.git;a=commit;h=11d6386
>
> The Makefile.in in my local git repo is correct, i.e.
> man/uname.1: src/uname
> whereas in the dist tarball it's
> man/uname.1: src/uname.c
>
> I might get time to investigate some time tomorrow.
>
This issue has already cropped up before, and I think I have managed
to diagnose it. See:
<http://lists.gnu.org/archive/html/coreutils/2012-09/msg00110.html>
There is also a patch available, but it doesn't seem to have
encountered much acceptance unfortunately:
<http://lists.gnu.org/archive/html/coreutils/2012-09/msg00132.html>
Regards,
Stefano
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 08:28:01 GMT)
Full text and
rfc822 format available.
Message #14 received at 12715 <at> debbugs.gnu.org (full text, mbox):
Stefano Lattarini <stefano.lattarini <at> gmail.com> writes:
> There is also a patch available, but it doesn't seem to have
> encountered much acceptance unfortunately:
>
> <http://lists.gnu.org/archive/html/coreutils/2012-09/msg00132.html>
The easiest way to solve that is to use order-only dependencies.
Andreas.
--
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5
"And now for something completely different."
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 09:23:02 GMT)
Full text and
rfc822 format available.
Message #17 received at 12715 <at> debbugs.gnu.org (full text, mbox):
Andreas Schwab wrote:
> Stefano Lattarini <stefano.lattarini <at> gmail.com> writes:
>
>> There is also a patch available, but it doesn't seem to have
>> encountered much acceptance unfortunately:
>>
>> <http://lists.gnu.org/archive/html/coreutils/2012-09/msg00132.html>
>
> The easiest way to solve that is to use order-only dependencies.
Yes, that would be perfect if we could rely on GNU make:
http://www.gnu.org/s/make/manual/html_node/Prerequisite-Types.html
If you had to require one, which would you rather mandate (rhetorical):
Gnu make
perl
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 09:25:02 GMT)
Full text and
rfc822 format available.
Message #20 received at 12715 <at> debbugs.gnu.org (full text, mbox):
On 10/24/2012 10:25 AM, Andreas Schwab wrote:
> Stefano Lattarini <stefano.lattarini <at> gmail.com> writes:
>
>> There is also a patch available, but it doesn't seem to have
>> encountered much acceptance unfortunately:
>>
>> <http://lists.gnu.org/archive/html/coreutils/2012-09/msg00132.html>
>
> The easiest way to solve that is to use order-only dependencies.
>
Which we unfortunately can't do, because they are a GNU make only feature.
Regards,
Stefano
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 10:41:01 GMT)
Full text and
rfc822 format available.
Message #23 received at 12715 <at> debbugs.gnu.org (full text, mbox):
On 10/24/2012 11:31 AM, Stefano Lattarini wrote:
> On 10/24/2012 10:54 AM, Jim Meyering wrote:
>> Pádraig Brady wrote:
>>
>>> `echo "warning"; touch $manpage`.
>>
>> Sounds good. I.e., it sounds like we want Stefano's patch, after all.
>>
>> As you recall, a nice side effect is that we will
>> no longer distribute the generated man/*.1 files.
>>
>> Stefano, would you care to rebase your patch?
>>
> Will do soon. Just give me some time to also re-test it ...
>
Done. The patch is inlined below.
Regards,
Stefano
----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----
From 6f35e53d98e6dc0c7843b9e434addf81d901aefa Mon Sep 17 00:00:00 2001
Message-Id: <6f35e53d98e6dc0c7843b9e434addf81d901aefa.1351075054.git.stefano.lattarini <at> gmail.com>
From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
Date: Tue, 11 Sep 2012 20:54:30 +0200
Subject: [PATCH] build: graceful degradation in man pages generation if perl
is lacking
Fixes coreutils bug#12715.
Since commit v8.19-118-g57da212, our 'dist-hook' rule tweaks the
distributed Makefile.in so that each man page 'man/foo.1' depends
on the corresponding source 'man/foo.c' rather than the corresponding
program 'man/foo'. That is done to accommodate inferior systems that,
lacking perl, cannot run 'help2man' to regenerate the manpage after
its corresponding program has been built.
This seems a right and proper graceful degradation, in that the
man pages dependencies are still 100% correct in a git checkout,
while being laxer but "more portable" in a distribution tarball.
Alas, that is not the case in practice, as it turns out the tweaked
Makefile makes the building of man pages unreliable and potentially
incorrect!
In fact, assume that instead of the correct a dependency:
man/ls.1: src/ls
we have the laxer one:
man/ls.1: src/ls.c
and think of what happens if a user modifies, say, 'src/ls.c', and then
runs "make -j4" to rebuild everything. The make process will see that
it has to rebuild the man page 'man/ls.1' (because its prerequisite
'src/ls.c' has changed), but won't see that it has to rebuild 'src/ls'
*before* re-running 'help2man' to generate that man page; so, if
'man/ls.1' is rebuilt before 'src/ls' (which can happen with concurrent
make), our user will get either a build error (if 'src/ls' did non
exist) or, worse, a man page with an up-to-date timestamp but an
out-of-date content. And what's even worse in all of this is that
this problem will be present also for users who have perl installed:
this is not a "graceful degradation" at all!
In our situation, the best and simplest way to implement a graceful
degradation it to keep the correct dependencies for man pages (that
is, "man/ls.1: src/ls"), and if perl is not present, just generate
dummy man pages reporting that built-time issue and redirecting the
user back to either the info documentation or the '--help' output.
As a consequence of this change, we also stop distributing man pages,
since they would be anyway unconditionally rebuilt
* Makefile.am (do-not-require-help2man): Remove.
(dist-hook): Don't depend on it.
* man/local.mk: Remove an obsolete comment.
(EXTRA_DIST): Stop distributing generated man pages.
($(EXTRA_MANS)): This no longer needs to depend on $(all_programs).
(MAINTAINERCLEANFILES): $(ALL_MANS) should not be listed here ...
(CLEANFILES): ... but here.
(.x.1): Instead of warning if perl is missing, but then trying to run
'help2man' unconditionally, simply run ...
(run_help2man): ... the command referenced by this new variable, that
expands to a proper invocation of 'help2man' if perl is present, and
to an invocation of a shell script generating a dummy manpage if it's
not.
(EXTRA_DIST): Distribute that shell script.
* man/dummy-man: Be that shell script
---
Makefile.am | 20 +----------------
man/dummy-man | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
man/local.mk | 25 +++++++++++----------
3 files changed, 86 insertions(+), 31 deletions(-)
create mode 100755 man/dummy-man
diff --git a/Makefile.am b/Makefile.am
index 0232090..5eaa45b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -93,29 +93,11 @@ BUILT_SOURCES = .version
.version:
$(AM_V_GEN)echo $(VERSION) > $@-t && mv $@-t $@
-# In general, we run help2man to build a man page from the binary's --help
-# output, but when building from a just-unpacked distribution tarball, we
-# must not do that, since help2man uses perl. We don't want to depend on
-# perl in that case. In general, the .1 file does indeed depend on the
-# binary. I.e., for cat, we have this Makefile dependency:
-# man/cat.1: src/cat
-# That means that once we build src/cat, we would trigger the .x.1
-# rule which runs help2man. The trick is simply to change the RHS to
-# "src/cat.c" in the $(distdir) that we're about to tar and compress.
-# Also handle the three exceptions corresponding to the three binaries
-# for which there is no like-named .c file: dir, vdir, ginstall.
-.PHONY: do-not-require-help2man
-do-not-require-help2man:
- perl -pi -e 's,^(man/.+?\.1:\s*src/.+?)$$,$$1.c,;' \
- -e 's,^(man/.+?\.1:\s*src)/ginstall\.c$$,$$1/install.c,;' \
- -e 's,^(man/.+?\.1:\s*src)/v?dir\.c$$,$$1/ls.c,;' \
- $(distdir)/Makefile.in
-
# Arrange so that .tarball-version appears only in the distribution
# tarball, and never in a checked-out repository.
# The perl substitution is to change some key uses of "rm" to "/bin/rm".
# See the rm_subst comment for details.
-dist-hook: gen-ChangeLog do-not-require-help2man
+dist-hook: gen-ChangeLog
$(AM_V_GEN)echo $(VERSION) > $(distdir)/.tarball-version
$(AM_V_at)perl -pi -e '$(rm_subst)' $(distdir)/Makefile.in
diff --git a/man/dummy-man b/man/dummy-man
new file mode 100755
index 0000000..cba661c
--- /dev/null
+++ b/man/dummy-man
@@ -0,0 +1,72 @@
+#!/bin/sh
+# Poor place holder for help2man invocation on systems lacking perl;
+# it generates a dummy manpage stating that as proper manpage could
+# not be generated, and redirecting the user back to either the info
+# documentation or the '--help' output.
+
+set -e; set -u
+
+fatal_ ()
+{
+ printf '%s: %s\n' "$0" "$*" >&2
+ exit 1
+}
+
+basename_ ()
+{
+ printf '%s\n' "$1" | sed 's,.*/,,'
+}
+
+output=
+source="GNU coreutils"
+while test $# -gt 0; do
+ case $1 in
+ # Help2man options we recognize handle.
+ --output=*) output=`expr x"$1" : x'--output=\(.*\)'`;;
+ --output) shift; output=$1;;
+ --source=*) source=`expr x"$1" : x'--source=\(.*\)'`;;
+ --source) shift; source=$1;;
+ # Recognize (as no-op) other help2man options that might be used
+ # in the makefile.
+ --include=*);;
+ --include) shift;;
+ -*) fatal_ "invalid or unrecognized help2man option '$1'";;
+ --) shift; break;;
+ *) break;;
+ esac
+ shift
+done
+
+test $# -gt 0 || fatal_ "missing argument"
+test $# -le 1 || fatal_ "too many non-option arguments"
+
+baseout=`basename "$output"`
+sed 's/^/WARNING: /' >&2 <<END
+Cannot create proper man page '$baseout' since perl is missing or
+inadequate on this system. Will create a stub man page instead.
+END
+
+progname=`basename_ "$1"`
+year=`LC_ALL=C date +%Y`
+bs='\'
+
+cat >"$output" <<END
+.TH "$progname" 1 "$year" "$source" "User Commands"
+.SH NAME
+$progname $bs- a GNU coreutils program
+.SH DESCRIPTION
+.B OOOPS!
+Due to lack of perl on your system, the GNU coreutils build system
+hasn't been able to create the manual page for
+.B $progname.
+For a quick help about that program, try running
+.IP
+.B env $progname --help
+.PP
+The full documentation for
+.B $progname
+is maintained as a Texinfo manual, which you might be accessible
+on your system with the command
+.IP
+.B info coreutils $bs(aq$progname invocation$bs(aq
+END
diff --git a/man/local.mk b/man/local.mk
index ebc111d..2c05bb6 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -16,17 +16,24 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
-EXTRA_DIST += man/help2man
+EXTRA_DIST += man/help2man man/dummy-man
+
+## Graceful degradation for systems lacking perl.
+if HAVE_PERL
+run_help2man = $(PERL) -- $(srcdir)/man/help2man
+else
+run_help2man = $(SHELL) $(srcdir)/man/dummy-man
+endif
man1_MANS = @man1_MANS@
-EXTRA_DIST += $(man1_MANS) $(man1_MANS:.1=.x)
+EXTRA_DIST += $(man1_MANS:.1=.x)
EXTRA_MANS = @EXTRA_MANS@
-EXTRA_DIST += $(EXTRA_MANS) $(EXTRA_MANS:.1=.x)
+EXTRA_DIST += $(EXTRA_MANS:.1=.x)
ALL_MANS = $(man1_MANS) $(EXTRA_MANS)
-MAINTAINERCLEANFILES += $(ALL_MANS)
+CLEANFILES += $(ALL_MANS)
# This is required because we have subtle inter-directory dependencies:
# in order to generate all man pages, even those for which we don't
@@ -161,13 +168,7 @@ man/whoami.1: src/whoami
man/yes.1: src/yes
.x.1:
- $(AM_V_GEN)case '$(PERL)' in \
- *"/missing "*) \
- echo 'WARNING: cannot update man page $@ since perl is missing' \
- 'or inadequate' 1>&2 \
- exit 0;; \
- esac; \
- name=`echo $@ | sed -e 's|.*/||' -e 's|\.1$$||'` || exit 1; \
+ $(AM_V_GEN)name=`echo $@ | sed 's|.*/||; s|\.1$$||'` || exit 1; \
## Ensure that help2man runs the 'src/ginstall' binary as 'install' when
## creating 'install.1'. Similarly, ensure that it uses the 'src/[' binary
## to create 'test.1'.
@@ -184,7 +185,7 @@ man/yes.1: src/yes
&& rm -rf $$t \
&& $(MKDIR_P) $$t \
&& (cd $$t && $(LN_S) '$(abs_top_builddir)/src/'$$prog $$name) \
- && $(PERL) -- $(srcdir)/man/help2man \
+ && $(run_help2man) \
--source='$(PACKAGE_STRING)' \
--include=$(srcdir)/man/$$name.x \
--output=$$t/$$name.1 $$t/$$name \
--
1.8.0.rc2.11.gd25c58c
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 10:49:02 GMT)
Full text and
rfc822 format available.
Message #26 received at 12715 <at> debbugs.gnu.org (full text, mbox):
On 10/24/2012 12:38 PM, Stefano Lattarini wrote:
> On 10/24/2012 11:31 AM, Stefano Lattarini wrote:
>> On 10/24/2012 10:54 AM, Jim Meyering wrote:
>>> Pádraig Brady wrote:
>>>
>>>> `echo "warning"; touch $manpage`.
>>>
>>> Sounds good. I.e., it sounds like we want Stefano's patch, after all.
>>>
>>> As you recall, a nice side effect is that we will
>>> no longer distribute the generated man/*.1 files.
>>>
>>> Stefano, would you care to rebase your patch?
>>>
>> Will do soon. Just give me some time to also re-test it ...
>>
> Done. The patch is inlined below.
>
Yikes, some blunders slipped in. We need at least the following diffs
squashed in:
-*-*-*-
diff --git a/man/dummy-man b/man/dummy-man
index cba661c..2e32320 100755
--- a/man/dummy-man
+++ b/man/dummy-man
@@ -1,5 +1,5 @@
#!/bin/sh
-# Poor place holder for help2man invocation on systems lacking perl;
+# Poor placeholder for help2man invocation on systems lacking perl;
# it generates a dummy manpage stating that as proper manpage could
# not be generated, and redirecting the user back to either the info
# documentation or the '--help' output.
@@ -21,7 +21,7 @@ output=
source="GNU coreutils"
while test $# -gt 0; do
case $1 in
- # Help2man options we recognize handle.
+ # Help2man options we recognize and handle.
--output=*) output=`expr x"$1" : x'--output=\(.*\)'`;;
--output) shift; output=$1;;
--source=*) source=`expr x"$1" : x'--source=\(.*\)'`;;
@@ -40,7 +40,7 @@ done
test $# -gt 0 || fatal_ "missing argument"
test $# -le 1 || fatal_ "too many non-option arguments"
-baseout=`basename "$output"`
+baseout=`basename_ "$output"`
sed 's/^/WARNING: /' >&2 <<END
Cannot create proper man page '$baseout' since perl is missing or
inadequate on this system. Will create a stub man page instead.
-*-*-*-
Here is the updated patch. Sorry for the noise,
Stefano
----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----
From f61dcb763975c1aab299fa9678ea180d70db6acf Mon Sep 17 00:00:00 2001
Message-Id: <f61dcb763975c1aab299fa9678ea180d70db6acf.1351075572.git.stefano.lattarini <at> gmail.com>
From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
Date: Tue, 11 Sep 2012 20:54:30 +0200
Subject: [PATCH] build: graceful degradation in man pages generation if perl
is lacking
Fixes coreutils bug#12715.
Since commit v8.19-118-g57da212, our 'dist-hook' rule tweaks the
distributed Makefile.in so that each man page 'man/foo.1' depends
on the corresponding source 'man/foo.c' rather than the corresponding
program 'man/foo'. That is done to accommodate inferior systems that,
lacking perl, cannot run 'help2man' to regenerate the manpage after
its corresponding program has been built.
This seems a right and proper graceful degradation, in that the
man pages dependencies are still 100% correct in a git checkout,
while being laxer but "more portable" in a distribution tarball.
Alas, that is not the case in practice, as it turns out the tweaked
Makefile makes the building of man pages unreliable and potentially
incorrect!
In fact, assume that instead of the correct a dependency:
man/ls.1: src/ls
we have the laxer one:
man/ls.1: src/ls.c
and think of what happens if a user modifies, say, 'src/ls.c', and then
runs "make -j4" to rebuild everything. The make process will see that
it has to rebuild the man page 'man/ls.1' (because its prerequisite
'src/ls.c' has changed), but won't see that it has to rebuild 'src/ls'
*before* re-running 'help2man' to generate that man page; so, if
'man/ls.1' is rebuilt before 'src/ls' (which can happen with concurrent
make), our user will get either a build error (if 'src/ls' did non
exist) or, worse, a man page with an up-to-date timestamp but an
out-of-date content. And what's even worse in all of this is that
this problem will be present also for users who have perl installed:
this is not a "graceful degradation" at all!
In our situation, the best and simplest way to implement a graceful
degradation it to keep the correct dependencies for man pages (that
is, "man/ls.1: src/ls"), and if perl is not present, just generate
dummy man pages reporting that built-time issue and redirecting the
user back to either the info documentation or the '--help' output.
As a consequence of this change, we also stop distributing man pages,
since they would be anyway unconditionally rebuilt
* Makefile.am (do-not-require-help2man): Remove.
(dist-hook): Don't depend on it.
* man/local.mk: Remove an obsolete comment.
(EXTRA_DIST): Stop distributing generated man pages.
($(EXTRA_MANS)): This no longer needs to depend on $(all_programs).
(MAINTAINERCLEANFILES): $(ALL_MANS) should not be listed here ...
(CLEANFILES): ... but here.
(.x.1): Instead of warning if perl is missing, but then trying to run
'help2man' unconditionally, simply run ...
(run_help2man): ... the command referenced by this new variable, that
expands to a proper invocation of 'help2man' if perl is present, and
to an invocation of a shell script generating a dummy manpage if it's
not.
(EXTRA_DIST): Distribute that shell script.
* man/dummy-man: Be that shell script
---
Makefile.am | 20 +----------------
man/dummy-man | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
man/local.mk | 25 +++++++++++----------
3 files changed, 86 insertions(+), 31 deletions(-)
create mode 100755 man/dummy-man
diff --git a/Makefile.am b/Makefile.am
index 0232090..5eaa45b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -93,29 +93,11 @@ BUILT_SOURCES = .version
.version:
$(AM_V_GEN)echo $(VERSION) > $@-t && mv $@-t $@
-# In general, we run help2man to build a man page from the binary's --help
-# output, but when building from a just-unpacked distribution tarball, we
-# must not do that, since help2man uses perl. We don't want to depend on
-# perl in that case. In general, the .1 file does indeed depend on the
-# binary. I.e., for cat, we have this Makefile dependency:
-# man/cat.1: src/cat
-# That means that once we build src/cat, we would trigger the .x.1
-# rule which runs help2man. The trick is simply to change the RHS to
-# "src/cat.c" in the $(distdir) that we're about to tar and compress.
-# Also handle the three exceptions corresponding to the three binaries
-# for which there is no like-named .c file: dir, vdir, ginstall.
-.PHONY: do-not-require-help2man
-do-not-require-help2man:
- perl -pi -e 's,^(man/.+?\.1:\s*src/.+?)$$,$$1.c,;' \
- -e 's,^(man/.+?\.1:\s*src)/ginstall\.c$$,$$1/install.c,;' \
- -e 's,^(man/.+?\.1:\s*src)/v?dir\.c$$,$$1/ls.c,;' \
- $(distdir)/Makefile.in
-
# Arrange so that .tarball-version appears only in the distribution
# tarball, and never in a checked-out repository.
# The perl substitution is to change some key uses of "rm" to "/bin/rm".
# See the rm_subst comment for details.
-dist-hook: gen-ChangeLog do-not-require-help2man
+dist-hook: gen-ChangeLog
$(AM_V_GEN)echo $(VERSION) > $(distdir)/.tarball-version
$(AM_V_at)perl -pi -e '$(rm_subst)' $(distdir)/Makefile.in
diff --git a/man/dummy-man b/man/dummy-man
new file mode 100755
index 0000000..2e32320
--- /dev/null
+++ b/man/dummy-man
@@ -0,0 +1,72 @@
+#!/bin/sh
+# Poor placeholder for help2man invocation on systems lacking perl;
+# it generates a dummy manpage stating that as proper manpage could
+# not be generated, and redirecting the user back to either the info
+# documentation or the '--help' output.
+
+set -e; set -u
+
+fatal_ ()
+{
+ printf '%s: %s\n' "$0" "$*" >&2
+ exit 1
+}
+
+basename_ ()
+{
+ printf '%s\n' "$1" | sed 's,.*/,,'
+}
+
+output=
+source="GNU coreutils"
+while test $# -gt 0; do
+ case $1 in
+ # Help2man options we recognize and handle.
+ --output=*) output=`expr x"$1" : x'--output=\(.*\)'`;;
+ --output) shift; output=$1;;
+ --source=*) source=`expr x"$1" : x'--source=\(.*\)'`;;
+ --source) shift; source=$1;;
+ # Recognize (as no-op) other help2man options that might be used
+ # in the makefile.
+ --include=*);;
+ --include) shift;;
+ -*) fatal_ "invalid or unrecognized help2man option '$1'";;
+ --) shift; break;;
+ *) break;;
+ esac
+ shift
+done
+
+test $# -gt 0 || fatal_ "missing argument"
+test $# -le 1 || fatal_ "too many non-option arguments"
+
+baseout=`basename_ "$output"`
+sed 's/^/WARNING: /' >&2 <<END
+Cannot create proper man page '$baseout' since perl is missing or
+inadequate on this system. Will create a stub man page instead.
+END
+
+progname=`basename_ "$1"`
+year=`LC_ALL=C date +%Y`
+bs='\'
+
+cat >"$output" <<END
+.TH "$progname" 1 "$year" "$source" "User Commands"
+.SH NAME
+$progname $bs- a GNU coreutils program
+.SH DESCRIPTION
+.B OOOPS!
+Due to lack of perl on your system, the GNU coreutils build system
+hasn't been able to create the manual page for
+.B $progname.
+For a quick help about that program, try running
+.IP
+.B env $progname --help
+.PP
+The full documentation for
+.B $progname
+is maintained as a Texinfo manual, which you might be accessible
+on your system with the command
+.IP
+.B info coreutils $bs(aq$progname invocation$bs(aq
+END
diff --git a/man/local.mk b/man/local.mk
index ebc111d..2c05bb6 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -16,17 +16,24 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
-EXTRA_DIST += man/help2man
+EXTRA_DIST += man/help2man man/dummy-man
+
+## Graceful degradation for systems lacking perl.
+if HAVE_PERL
+run_help2man = $(PERL) -- $(srcdir)/man/help2man
+else
+run_help2man = $(SHELL) $(srcdir)/man/dummy-man
+endif
man1_MANS = @man1_MANS@
-EXTRA_DIST += $(man1_MANS) $(man1_MANS:.1=.x)
+EXTRA_DIST += $(man1_MANS:.1=.x)
EXTRA_MANS = @EXTRA_MANS@
-EXTRA_DIST += $(EXTRA_MANS) $(EXTRA_MANS:.1=.x)
+EXTRA_DIST += $(EXTRA_MANS:.1=.x)
ALL_MANS = $(man1_MANS) $(EXTRA_MANS)
-MAINTAINERCLEANFILES += $(ALL_MANS)
+CLEANFILES += $(ALL_MANS)
# This is required because we have subtle inter-directory dependencies:
# in order to generate all man pages, even those for which we don't
@@ -161,13 +168,7 @@ man/whoami.1: src/whoami
man/yes.1: src/yes
.x.1:
- $(AM_V_GEN)case '$(PERL)' in \
- *"/missing "*) \
- echo 'WARNING: cannot update man page $@ since perl is missing' \
- 'or inadequate' 1>&2 \
- exit 0;; \
- esac; \
- name=`echo $@ | sed -e 's|.*/||' -e 's|\.1$$||'` || exit 1; \
+ $(AM_V_GEN)name=`echo $@ | sed 's|.*/||; s|\.1$$||'` || exit 1; \
## Ensure that help2man runs the 'src/ginstall' binary as 'install' when
## creating 'install.1'. Similarly, ensure that it uses the 'src/[' binary
## to create 'test.1'.
@@ -184,7 +185,7 @@ man/yes.1: src/yes
&& rm -rf $$t \
&& $(MKDIR_P) $$t \
&& (cd $$t && $(LN_S) '$(abs_top_builddir)/src/'$$prog $$name) \
- && $(PERL) -- $(srcdir)/man/help2man \
+ && $(run_help2man) \
--source='$(PACKAGE_STRING)' \
--include=$(srcdir)/man/$$name.x \
--output=$$t/$$name.1 $$t/$$name \
--
1.8.0.rc2.11.gd25c58c
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 13:10:01 GMT)
Full text and
rfc822 format available.
Message #29 received at 12715 <at> debbugs.gnu.org (full text, mbox):
Stefano Lattarini wrote:
> Here is the updated patch. Sorry for the noise,
...
> Subject: [PATCH] build: graceful degradation in man pages generation if perl
> is lacking
Thank you for the updated patch.
> Fixes coreutils bug#12715.
>
> Since commit v8.19-118-g57da212, our 'dist-hook' rule tweaks the
> distributed Makefile.in so that each man page 'man/foo.1' depends
> on the corresponding source 'man/foo.c' rather than the corresponding
> program 'man/foo'. That is done to accommodate inferior systems that,
> lacking perl, cannot run 'help2man' to regenerate the manpage after
> its corresponding program has been built.
>
> This seems a right and proper graceful degradation, in that the
> man pages dependencies are still 100% correct in a git checkout,
> while being laxer but "more portable" in a distribution tarball.
>
> Alas, that is not the case in practice, as it turns out the tweaked
> Makefile makes the building of man pages unreliable and potentially
> incorrect!
>
> In fact, assume that instead of the correct a dependency:
>
> man/ls.1: src/ls
>
> we have the laxer one:
>
> man/ls.1: src/ls.c
>
> and think of what happens if a user modifies, say, 'src/ls.c', and then
> runs "make -j4" to rebuild everything. The make process will see that
> it has to rebuild the man page 'man/ls.1' (because its prerequisite
> 'src/ls.c' has changed), but won't see that it has to rebuild 'src/ls'
> *before* re-running 'help2man' to generate that man page; so, if
> 'man/ls.1' is rebuilt before 'src/ls' (which can happen with concurrent
> make), our user will get either a build error (if 'src/ls' did non
> exist) or, worse, a man page with an up-to-date timestamp but an
> out-of-date content. And what's even worse in all of this is that
> this problem will be present also for users who have perl installed:
> this is not a "graceful degradation" at all!
>
> In our situation, the best and simplest way to implement a graceful
> degradation it to keep the correct dependencies for man pages (that
> is, "man/ls.1: src/ls"), and if perl is not present, just generate
> dummy man pages reporting that built-time issue and redirecting the
> user back to either the info documentation or the '--help' output.
>
> As a consequence of this change, we also stop distributing man pages,
> since they would be anyway unconditionally rebuilt
This is simpler than what Pádraig suggested (distribute
.1 files and insert warning if needed), but I'm inclined to
agree that simpler is better.
Does anyone know of a well-known environment/distro in which
coreutils is built without perl? I.e., if virtually no one
builds coreutils without perl, then any attempt to coddle those
users is wasted complexity.
> * Makefile.am (do-not-require-help2man): Remove.
> (dist-hook): Don't depend on it.
> * man/local.mk: Remove an obsolete comment.
> (EXTRA_DIST): Stop distributing generated man pages.
> ($(EXTRA_MANS)): This no longer needs to depend on $(all_programs).
> (MAINTAINERCLEANFILES): $(ALL_MANS) should not be listed here ...
> (CLEANFILES): ... but here.
> (.x.1): Instead of warning if perl is missing, but then trying to run
> 'help2man' unconditionally, simply run ...
> (run_help2man): ... the command referenced by this new variable, that
> expands to a proper invocation of 'help2man' if perl is present, and
> to an invocation of a shell script generating a dummy manpage if it's
> not.
> (EXTRA_DIST): Distribute that shell script.
> * man/dummy-man: Be that shell script
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 14:07:01 GMT)
Full text and
rfc822 format available.
Message #32 received at 12715 <at> debbugs.gnu.org (full text, mbox):
----- Mail original -----
> De: "Jim Meyering" <jim <at> meyering.net>
> À: "Stefano Lattarini" <stefano.lattarini <at> gmail.com>
> Cc: "Pádraig Brady" <P <at> draigBrady.com>, "Mike Frysinger" <vapier <at> gentoo.org>, coreutils <at> gnu.org,
> 12715 <at> debbugs.gnu.org
> Envoyé: Mercredi 24 Octobre 2012 15:07:18
> Objet: bug#12715: [PATCH] build: do not require help2man at build-from-tarball time
>
> Stefano Lattarini wrote:
> > Here is the updated patch. Sorry for the noise,
> ...
> > Subject: [PATCH] build: graceful degradation in man pages
> > generation if perl
> > is lacking
>
>
> Does anyone know of a well-known environment/distro in which
> coreutils is built without perl? I.e., if virtually no one
> builds coreutils without perl, then any attempt to coddle those
> users is wasted complexity.
>
Speaking for what I know, this is not an issue with 'linux from scratch' based systems.
- perl is an host requirement (coreutils is build a first time on toolchain stage),
- perl is build on toolchain stage before final coreutils is build.
Any toolchain that really cross-compile often avoid perl as notoriously hard to cross-compile.
Often busybox is used instead of coreutils. Openwrt for example does that.
Openwrt could optionally build coreutils. The build script use 8.16 and patch to not build the doc.
Gilles
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Wed, 24 Oct 2012 14:20:02 GMT)
Full text and
rfc822 format available.
Message #35 received at 12715 <at> debbugs.gnu.org (full text, mbox):
g.esp <at> free.fr wrote:
> ----- Mail original -----
>> De: "Jim Meyering" <jim <at> meyering.net>
>> À: "Stefano Lattarini" <stefano.lattarini <at> gmail.com>
>> Cc: "Pádraig Brady" <P <at> draigBrady.com>, "Mike Frysinger"
>> <vapier <at> gentoo.org>, coreutils <at> gnu.org,
>> 12715 <at> debbugs.gnu.org
>> Envoyé: Mercredi 24 Octobre 2012 15:07:18
>> Objet: bug#12715: [PATCH] build: do not require help2man at
>> build-from-tarball time
>>
>> Stefano Lattarini wrote:
>> > Here is the updated patch. Sorry for the noise,
>> ...
>> > Subject: [PATCH] build: graceful degradation in man pages
>> > generation if perl
>> > is lacking
>>
>> Does anyone know of a well-known environment/distro in which
>> coreutils is built without perl? I.e., if virtually no one
>> builds coreutils without perl, then any attempt to coddle those
>> users is wasted complexity.
>>
> Speaking for what I know, this is not an issue with 'linux from
> scratch' based systems.
> - perl is an host requirement (coreutils is build a first time on
> toolchain stage),
> - perl is build on toolchain stage before final coreutils is build.
>
> Any toolchain that really cross-compile often avoid perl as
> notoriously hard to cross-compile.
> Often busybox is used instead of coreutils. Openwrt for example does that.
> Openwrt could optionally build coreutils. The build script use 8.16
> and patch to not build the doc.
Nice. That's reassuring.
Thanks for the info.
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Thu, 25 Oct 2012 13:40:01 GMT)
Full text and
rfc822 format available.
Message #38 received at 12715 <at> debbugs.gnu.org (full text, mbox):
Stefano Lattarini wrote:
...
> Here is the updated patch. Sorry for the noise,
> Stefano
>
> ----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----
>
>>From f61dcb763975c1aab299fa9678ea180d70db6acf Mon Sep 17 00:00:00 2001
> Message-Id: <f61dcb763975c1aab299fa9678ea180d70db6acf.1351075572.git.stefano.lattarini <at> gmail.com>
> From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
> Date: Tue, 11 Sep 2012 20:54:30 +0200
> Subject: [PATCH] build: graceful degradation in man pages generation if perl
Thanks. That looks good.
I've made some minor changes. Here's an incremental:
diff --git a/man/dummy-man b/man/dummy-man
index 2e32320..633a5ba 100755
--- a/man/dummy-man
+++ b/man/dummy-man
@@ -1,7 +1,7 @@
#!/bin/sh
-# Poor placeholder for help2man invocation on systems lacking perl;
-# it generates a dummy manpage stating that as proper manpage could
-# not be generated, and redirecting the user back to either the info
+# Poor man's placeholder for help2man invocation on systems lacking perl;
+# it generates a dummy man page stating that a proper one could not be
+# generated, and redirecting the user back to either the info
# documentation or the '--help' output.
set -e; set -u
@@ -42,8 +42,8 @@ test $# -le 1 || fatal_ "too many non-option arguments"
baseout=`basename_ "$output"`
sed 's/^/WARNING: /' >&2 <<END
-Cannot create proper man page '$baseout' since perl is missing or
-inadequate on this system. Will create a stub man page instead.
+Cannot create proper '$baseout' man page, since perl is missing or
+inadequate on this system. Creating a stub man page instead.
END
progname=`basename_ "$1"`
@@ -53,20 +53,20 @@ bs='\'
cat >"$output" <<END
.TH "$progname" 1 "$year" "$source" "User Commands"
.SH NAME
-$progname $bs- a GNU coreutils program
+$progname $bs- a $source program
.SH DESCRIPTION
.B OOOPS!
-Due to lack of perl on your system, the GNU coreutils build system
-hasn't been able to create the manual page for
+Due to lack of perl on your system, the $source build system
+failed to create the manual page for
.B $progname.
-For a quick help about that program, try running
+For concise option descriptions, run
.IP
.B env $progname --help
.PP
The full documentation for
.B $progname
-is maintained as a Texinfo manual, which you might be accessible
-on your system with the command
+is maintained as a Texinfo manual, which should be accessible
+on your system via the command
.IP
.B info coreutils $bs(aq$progname invocation$bs(aq
END
Here is the merged result, also with an adjusted log. Ok?
----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----8<----
From 6f64d745fb2ce525a056b016ef4ada66416c9e8d Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <stefano.lattarini <at> gmail.com>
Date: Tue, 11 Sep 2012 20:54:30 +0200
Subject: [PATCH] build: graceful degradation in man pages generation if perl
is lacking
Since commit v8.19-118-g57da212, our 'dist-hook' rule tweaks the
distributed Makefile.in so that each man page 'man/foo.1' depends
on the corresponding source 'src/foo.c' rather than the corresponding
program 'src/foo'. That is done to accommodate inferior systems that,
lacking perl, cannot run help2man to regenerate the manpage after
its corresponding program has been built.
This seems a right and proper graceful degradation, in that the
man pages dependencies are still 100% correct in a git checkout,
while being laxer but "more portable" in a distribution tarball.
Alas, that is not the case in practice, as it turns out the tweaked
Makefile makes the building of man pages unreliable and potentially
incorrect!
In fact, assume that instead of the correct a dependency:
man/ls.1: src/ls
we have the laxer one:
man/ls.1: src/ls.c
and think of what happens if a user modifies, say, 'src/ls.c', and then
runs "make -j4" to rebuild everything. The make process will see that
it has to rebuild the man page 'man/ls.1' (because its prerequisite
'src/ls.c' has changed), but won't see that it has to rebuild 'src/ls'
*before* re-running 'help2man' to generate that man page; so, if
'man/ls.1' is rebuilt before 'src/ls' (which can happen with concurrent
make), our user will get either a build error (if 'src/ls' did non
exist) or, worse, a man page with an up-to-date timestamp but an
out-of-date content. And what's even worse in all of this is that
this problem will be present also for users who have perl installed:
this is not a "graceful degradation" at all!
In our situation, the best and simplest way to implement a graceful
degradation it to keep the correct dependencies for man pages (that
is, "man/ls.1: src/ls"), and if perl is not present, just generate
dummy man pages reporting that built-time issue and redirecting the
user back to either the info documentation or the '--help' output.
As a consequence of this change, we also stop distributing man pages,
since they will now be generated unconditionally.
* Makefile.am (do-not-require-help2man): Remove.
(dist-hook): Don't depend on it.
* man/local.mk: Remove an obsolete comment.
(EXTRA_DIST): Stop distributing generated man pages.
($(EXTRA_MANS)): This no longer needs to depend on $(all_programs).
(MAINTAINERCLEANFILES): $(ALL_MANS) Do not list it here, and ...
(CLEANFILES): ... list it here, instead.
(.x.1): Instead of warning if perl is missing, but then trying to run
'help2man' unconditionally, simply run ...
(run_help2man): ... the command referenced by this new variable, that
expands to a proper invocation of 'help2man' if perl is present, and
to an invocation of a shell script generating a dummy manpage if it
is not.
(EXTRA_DIST): Distribute that shell script.
* man/dummy-man: New shell script.
Fixes coreutils http://bugs.gnu.org/12715.
---
Makefile.am | 20 +----------------
man/dummy-man | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
man/local.mk | 25 +++++++++++----------
3 files changed, 86 insertions(+), 31 deletions(-)
create mode 100755 man/dummy-man
diff --git a/Makefile.am b/Makefile.am
index 0232090..5eaa45b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -93,29 +93,11 @@ BUILT_SOURCES = .version
.version:
$(AM_V_GEN)echo $(VERSION) > $@-t && mv $@-t $@
-# In general, we run help2man to build a man page from the binary's --help
-# output, but when building from a just-unpacked distribution tarball, we
-# must not do that, since help2man uses perl. We don't want to depend on
-# perl in that case. In general, the .1 file does indeed depend on the
-# binary. I.e., for cat, we have this Makefile dependency:
-# man/cat.1: src/cat
-# That means that once we build src/cat, we would trigger the .x.1
-# rule which runs help2man. The trick is simply to change the RHS to
-# "src/cat.c" in the $(distdir) that we're about to tar and compress.
-# Also handle the three exceptions corresponding to the three binaries
-# for which there is no like-named .c file: dir, vdir, ginstall.
-.PHONY: do-not-require-help2man
-do-not-require-help2man:
- perl -pi -e 's,^(man/.+?\.1:\s*src/.+?)$$,$$1.c,;' \
- -e 's,^(man/.+?\.1:\s*src)/ginstall\.c$$,$$1/install.c,;' \
- -e 's,^(man/.+?\.1:\s*src)/v?dir\.c$$,$$1/ls.c,;' \
- $(distdir)/Makefile.in
-
# Arrange so that .tarball-version appears only in the distribution
# tarball, and never in a checked-out repository.
# The perl substitution is to change some key uses of "rm" to "/bin/rm".
# See the rm_subst comment for details.
-dist-hook: gen-ChangeLog do-not-require-help2man
+dist-hook: gen-ChangeLog
$(AM_V_GEN)echo $(VERSION) > $(distdir)/.tarball-version
$(AM_V_at)perl -pi -e '$(rm_subst)' $(distdir)/Makefile.in
diff --git a/man/dummy-man b/man/dummy-man
new file mode 100755
index 0000000..633a5ba
--- /dev/null
+++ b/man/dummy-man
@@ -0,0 +1,72 @@
+#!/bin/sh
+# Poor man's placeholder for help2man invocation on systems lacking perl;
+# it generates a dummy man page stating that a proper one could not be
+# generated, and redirecting the user back to either the info
+# documentation or the '--help' output.
+
+set -e; set -u
+
+fatal_ ()
+{
+ printf '%s: %s\n' "$0" "$*" >&2
+ exit 1
+}
+
+basename_ ()
+{
+ printf '%s\n' "$1" | sed 's,.*/,,'
+}
+
+output=
+source="GNU coreutils"
+while test $# -gt 0; do
+ case $1 in
+ # Help2man options we recognize and handle.
+ --output=*) output=`expr x"$1" : x'--output=\(.*\)'`;;
+ --output) shift; output=$1;;
+ --source=*) source=`expr x"$1" : x'--source=\(.*\)'`;;
+ --source) shift; source=$1;;
+ # Recognize (as no-op) other help2man options that might be used
+ # in the makefile.
+ --include=*);;
+ --include) shift;;
+ -*) fatal_ "invalid or unrecognized help2man option '$1'";;
+ --) shift; break;;
+ *) break;;
+ esac
+ shift
+done
+
+test $# -gt 0 || fatal_ "missing argument"
+test $# -le 1 || fatal_ "too many non-option arguments"
+
+baseout=`basename_ "$output"`
+sed 's/^/WARNING: /' >&2 <<END
+Cannot create proper '$baseout' man page, since perl is missing or
+inadequate on this system. Creating a stub man page instead.
+END
+
+progname=`basename_ "$1"`
+year=`LC_ALL=C date +%Y`
+bs='\'
+
+cat >"$output" <<END
+.TH "$progname" 1 "$year" "$source" "User Commands"
+.SH NAME
+$progname $bs- a $source program
+.SH DESCRIPTION
+.B OOOPS!
+Due to lack of perl on your system, the $source build system
+failed to create the manual page for
+.B $progname.
+For concise option descriptions, run
+.IP
+.B env $progname --help
+.PP
+The full documentation for
+.B $progname
+is maintained as a Texinfo manual, which should be accessible
+on your system via the command
+.IP
+.B info coreutils $bs(aq$progname invocation$bs(aq
+END
diff --git a/man/local.mk b/man/local.mk
index ebc111d..2c05bb6 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -16,17 +16,24 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
-EXTRA_DIST += man/help2man
+EXTRA_DIST += man/help2man man/dummy-man
+
+## Graceful degradation for systems lacking perl.
+if HAVE_PERL
+run_help2man = $(PERL) -- $(srcdir)/man/help2man
+else
+run_help2man = $(SHELL) $(srcdir)/man/dummy-man
+endif
man1_MANS = @man1_MANS@
-EXTRA_DIST += $(man1_MANS) $(man1_MANS:.1=.x)
+EXTRA_DIST += $(man1_MANS:.1=.x)
EXTRA_MANS = @EXTRA_MANS@
-EXTRA_DIST += $(EXTRA_MANS) $(EXTRA_MANS:.1=.x)
+EXTRA_DIST += $(EXTRA_MANS:.1=.x)
ALL_MANS = $(man1_MANS) $(EXTRA_MANS)
-MAINTAINERCLEANFILES += $(ALL_MANS)
+CLEANFILES += $(ALL_MANS)
# This is required because we have subtle inter-directory dependencies:
# in order to generate all man pages, even those for which we don't
@@ -161,13 +168,7 @@ man/whoami.1: src/whoami
man/yes.1: src/yes
.x.1:
- $(AM_V_GEN)case '$(PERL)' in \
- *"/missing "*) \
- echo 'WARNING: cannot update man page $@ since perl is missing' \
- 'or inadequate' 1>&2 \
- exit 0;; \
- esac; \
- name=`echo $@ | sed -e 's|.*/||' -e 's|\.1$$||'` || exit 1; \
+ $(AM_V_GEN)name=`echo $@ | sed 's|.*/||; s|\.1$$||'` || exit 1; \
## Ensure that help2man runs the 'src/ginstall' binary as 'install' when
## creating 'install.1'. Similarly, ensure that it uses the 'src/[' binary
## to create 'test.1'.
@@ -184,7 +185,7 @@ man/yes.1: src/yes
&& rm -rf $$t \
&& $(MKDIR_P) $$t \
&& (cd $$t && $(LN_S) '$(abs_top_builddir)/src/'$$prog $$name) \
- && $(PERL) -- $(srcdir)/man/help2man \
+ && $(run_help2man) \
--source='$(PACKAGE_STRING)' \
--include=$(srcdir)/man/$$name.x \
--output=$$t/$$name.1 $$t/$$name \
--
1.8.0
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Thu, 25 Oct 2012 14:08:02 GMT)
Full text and
rfc822 format available.
Message #41 received at 12715 <at> debbugs.gnu.org (full text, mbox):
On 10/25/2012 03:37 PM, Jim Meyering wrote:
> -Due to lack of perl on your system, the GNU coreutils build system
> -hasn't been able to create the manual page for
> +Due to lack of perl on your system, the $source build system
> +failed to create the manual page for
Isn't it "Due to lack on the build system, ..."?
I.e. coreutils could be built on system A lacking perl,
and then be installed on system B which has perl. The above
text would be misleading in this case.
Have a nice day,
Berny
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Thu, 25 Oct 2012 14:11:02 GMT)
Full text and
rfc822 format available.
Message #44 received at 12715 <at> debbugs.gnu.org (full text, mbox):
Bernhard Voelker wrote:
> On 10/25/2012 03:37 PM, Jim Meyering wrote:
>> -Due to lack of perl on your system, the GNU coreutils build system
>> -hasn't been able to create the manual page for
>> +Due to lack of perl on your system, the $source build system
>> +failed to create the manual page for
>
> Isn't it "Due to lack on the build system, ..."?
>
> I.e. coreutils could be built on system A lacking perl,
> and then be installed on system B which has perl. The above
> text would be misleading in this case.
Good point.
I've merged this in:
diff --git a/man/dummy-man b/man/dummy-man
index 633a5ba..3069376 100755
--- a/man/dummy-man
+++ b/man/dummy-man
@@ -56,8 +56,8 @@ cat >"$output" <<END
$progname $bs- a $source program
.SH DESCRIPTION
.B OOOPS!
-Due to lack of perl on your system, the $source build system
-failed to create the manual page for
+Due to the lack of perl on the build system, we were
+unable to create a proper manual page for
.B $progname.
For concise option descriptions, run
.IP
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Thu, 25 Oct 2012 14:28:02 GMT)
Full text and
rfc822 format available.
Message #47 received at 12715 <at> debbugs.gnu.org (full text, mbox):
On 10/25/2012 04:08 PM, Jim Meyering wrote:
> Bernhard Voelker wrote:
>> Isn't it "Due to lack on the build system, ..."?
>>
>> I.e. coreutils could be built on system A lacking perl,
>> and then be installed on system B which has perl. The above
>> text would be misleading in this case.
>
> Good point.
> I've merged this in:
>
> diff --git a/man/dummy-man b/man/dummy-man
> index 633a5ba..3069376 100755
> --- a/man/dummy-man
> +++ b/man/dummy-man
> @@ -56,8 +56,8 @@ cat >"$output" <<END
> $progname $bs- a $source program
> .SH DESCRIPTION
> .B OOOPS!
> -Due to lack of perl on your system, the $source build system
> -failed to create the manual page for
> +Due to the lack of perl on the build system, we were
> +unable to create a proper manual page for
> .B $progname.
> For concise option descriptions, run
> .IP
Looks good, thanks.
Berny
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Fri, 26 Oct 2012 07:52:02 GMT)
Full text and
rfc822 format available.
Message #50 received at 12715 <at> debbugs.gnu.org (full text, mbox):
On 10/25/2012 04:25 PM, Bernhard Voelker wrote:
> On 10/25/2012 04:08 PM, Jim Meyering wrote:
>> Bernhard Voelker wrote:
>>> Isn't it "Due to lack on the build system, ..."?
>>>
>>> I.e. coreutils could be built on system A lacking perl,
>>> and then be installed on system B which has perl. The above
>>> text would be misleading in this case.
>>
>> Good point.
>> I've merged this in:
>>
>> diff --git a/man/dummy-man b/man/dummy-man
>> index 633a5ba..3069376 100755
>> --- a/man/dummy-man
>> +++ b/man/dummy-man
>> @@ -56,8 +56,8 @@ cat >"$output" <<END
>> $progname $bs- a $source program
>> .SH DESCRIPTION
>> .B OOOPS!
>> -Due to lack of perl on your system, the $source build system
>> -failed to create the manual page for
>> +Due to the lack of perl on the build system, we were
>> +unable to create a proper manual page for
>> .B $progname.
>> For concise option descriptions, run
>> .IP
>
> Looks good, thanks.
>
Fine by me as well.
Thanks,
Stefano
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Fri, 26 Oct 2012 09:37:01 GMT)
Full text and
rfc822 format available.
Message #53 received at 12715 <at> debbugs.gnu.org (full text, mbox):
Stefano Lattarini wrote:
> On 10/25/2012 04:25 PM, Bernhard Voelker wrote:
>> On 10/25/2012 04:08 PM, Jim Meyering wrote:
>>> Bernhard Voelker wrote:
>>>> Isn't it "Due to lack on the build system, ..."?
>>>>
>>>> I.e. coreutils could be built on system A lacking perl,
>>>> and then be installed on system B which has perl. The above
>>>> text would be misleading in this case.
>>>
>>> Good point.
>>> I've merged this in:
>>>
>>> diff --git a/man/dummy-man b/man/dummy-man
>>> index 633a5ba..3069376 100755
>>> --- a/man/dummy-man
>>> +++ b/man/dummy-man
>>> @@ -56,8 +56,8 @@ cat >"$output" <<END
>>> $progname $bs- a $source program
>>> .SH DESCRIPTION
>>> .B OOOPS!
>>> -Due to lack of perl on your system, the $source build system
>>> -failed to create the manual page for
>>> +Due to the lack of perl on the build system, we were
>>> +unable to create a proper manual page for
>>> .B $progname.
>>> For concise option descriptions, run
>>> .IP
>>
>> Looks good, thanks.
>>
> Fine by me as well.
This is definitely NEWS-worthy and I nearly forgot to add a NEWS entry.
Here's the adjusted log and NEWS diffs:
commit 2eeec4ebbdda9ed89263c815a4087675043b556a
Author: Stefano Lattarini <stefano.lattarini <at> gmail.com>
Date: Tue Sep 11 20:54:30 2012 +0200
build: man page generation: degrade gracefully when perl is lacking
Since commit v8.19-118-g57da212, our 'dist-hook' rule tweaked the
distributed Makefile.in to make each man page 'man/foo.1' depend
on the corresponding source 'src/foo.c' rather than the corresponding
program 'src/foo'. That was done to accommodate systems without
perl, which cannot run help2man to regenerate the manpage after
its corresponding program has been built.
This seems a right and proper graceful degradation, in that the
man pages dependencies are still 100% correct in a git checkout,
while being more lax but "more portable" in a distribution tarball.
Alas, that is not the case in practice, as it turns out the tweaked
Makefile makes the building of man pages unreliable and potentially
incorrect!
In fact, assume that instead of the correct a dependency:
man/ls.1: src/ls
we have the laxer one:
man/ls.1: src/ls.c
and think of what happens if a user modifies, say, 'src/ls.c', and then
runs "make -j4" to rebuild everything. The make process will see that
it has to rebuild the man page 'man/ls.1' (because its prerequisite
'src/ls.c' has changed), but won't see that it has to rebuild 'src/ls'
*before* re-running 'help2man' to generate that man page; so, if
'man/ls.1' is rebuilt before 'src/ls' (which can happen with concurrent
make), our user will get either a build error (if 'src/ls' did non
exist) or, worse, a man page with an up-to-date timestamp but an
out-of-date content. And what's even worse in all of this is that
this problem will be present also for users who have perl installed:
this is not a "graceful degradation" at all!
In our situation, the best and simplest way to implement a graceful
degradation it to keep the correct dependencies for man pages (that
is, "man/ls.1: src/ls"), and if perl is not present, just generate
dummy man pages reporting that built-time issue and redirecting the
user back to either the info documentation or the '--help' output.
As a consequence of this change, we also stop distributing man pages,
since they will now be generated unconditionally.
* Makefile.am (do-not-require-help2man): Remove.
(dist-hook): Don't depend on it.
* man/local.mk: Remove an obsolete comment.
(EXTRA_DIST): Stop distributing generated man pages.
($(EXTRA_MANS)): This no longer needs to depend on $(all_programs).
(MAINTAINERCLEANFILES): $(ALL_MANS) Do not list it here, and ...
(CLEANFILES): ... list it here, instead.
(.x.1): Instead of warning if perl is missing, but then trying to run
'help2man' unconditionally, simply run ...
(run_help2man): ... the command referenced by this new variable, that
expands to a proper invocation of 'help2man' if perl is present, and
to an invocation of a shell script generating a dummy manpage if it
is not.
(EXTRA_DIST): Distribute that shell script.
* man/dummy-man: New shell script.
* NEWS (Build-related): Mention this.
Fixes coreutils http://bugs.gnu.org/12715.
diff --git a/NEWS b/NEWS
index e13ba22..2d32ca5 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,14 @@ GNU coreutils NEWS -*- outline -*-
consistently padded with spaces, rather than with zeros for certain widths.
[bug introduced in TEXTUTILS-1_22i]
+** Build-related
+
+ The generated man/*.1 man pages are no longer distributed. Building
+ without perl, you would create stub man pages, and besides would be
+ unable to run a significant percentage of the tests (so don't do that!).
+ Thus, while perl is not an official prerequisite (build and "make check"
+ will still succeed), any resulting man pages would be inferior.
+
* Noteworthy changes in release 8.20 (2012-10-23) [stable]
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Fri, 26 Oct 2012 09:46:02 GMT)
Full text and
rfc822 format available.
Message #56 received at 12715 <at> debbugs.gnu.org (full text, mbox):
On 10/26/2012 10:34 AM, Jim Meyering wrote:
> +** Build-related
> +
> + The generated man/*.1 man pages are no longer distributed. Building
> + without perl, you would create stub man pages, and besides would be
> + unable to run a significant percentage of the tests (so don't do that!).
> + Thus, while perl is not an official prerequisite (build and "make check"
> + will still succeed), any resulting man pages would be inferior.
We should probably mention that this fixes a parallel build failure
when building modified sources, like a patched distro package for example.
thanks,
Pádraig.
Information forwarded
to
bug-coreutils <at> gnu.org:
bug#12715; Package
coreutils.
(Fri, 26 Oct 2012 09:53:02 GMT)
Full text and
rfc822 format available.
Message #59 received at 12715 <at> debbugs.gnu.org (full text, mbox):
Pádraig Brady wrote:
> On 10/26/2012 10:34 AM, Jim Meyering wrote:
>> +** Build-related
>> +
>> + The generated man/*.1 man pages are no longer distributed. Building
>> + without perl, you would create stub man pages, and besides would be
>> + unable to run a significant percentage of the tests (so don't do that!).
>> + Thus, while perl is not an official prerequisite (build and "make check"
>> + will still succeed), any resulting man pages would be inferior.
>
> We should probably mention that this fixes a parallel build failure
> when building modified sources, like a patched distro package for example.
Yes. Good point.
How about this?
I was tempted to note it in the "Bug fixes" section,
but figures this would be enough.
** Build-related
Perl is now more of a prerequisite. It has long been required in order
to run (not skip) a significant percentage of the tests. Now, it is
also required in order to generate proper man pages, via help2man. The
generated man/*.1 man pages are no longer distributed. Building without
perl, you would create stub man pages. Thus, while perl is not an
official prerequisite (build and "make check" will still succeed), any
resulting man pages would be inferior. In addition, this fixes a bug
in distributed (not from clone) Makefile.in that could cause parallel
build failure when building from modified sources, as is common practice
for a patched distribution package.
Added tag(s) fixed.
Request was from
Assaf Gordon <assafgordon <at> gmail.com>
to
control <at> debbugs.gnu.org.
(Mon, 15 Oct 2018 17:47:01 GMT)
Full text and
rfc822 format available.
bug closed, send any further explanations to
12715 <at> debbugs.gnu.org and Mike Frysinger <vapier <at> gentoo.org>
Request was from
Assaf Gordon <assafgordon <at> gmail.com>
to
control <at> debbugs.gnu.org.
(Mon, 15 Oct 2018 17:47:01 GMT)
Full text and
rfc822 format available.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Tue, 13 Nov 2018 12:24:04 GMT)
Full text and
rfc822 format available.
This bug report was last modified 5 years and 159 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.