Re: bug#12715: [PATCH] build: do not require help2man at build-from-tarball time

[Jim Meyering]

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 <address@hidden>
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]