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

[Stefano Lattarini]

On 09/10/2012 12:46 PM, Jim Meyering wrote:
> Stefano Lattarini wrote:
>> Hi Jim.
>>
>> On 09/10/2012 09:41 AM, Jim Meyering wrote:
>>> We can't have build-from-tarball requiring perl (via help2man)
>>> or regenerating a distributed .1 file when its .c file has not changed.
>>>
>>> From 57da212a95054cc230ffb00f38ea655c798926f8 Mon Sep 17 00:00:00 2001
>>> From: Jim Meyering <address@hidden>
>>> Date: Sun, 9 Sep 2012 19:27:25 +0200
>>> Subject: [PATCH] build: do not require help2man at build-from-tarball time
>>>
>>> But do retain full dependencies when building from a git clone.
>>> We do this by converting the full dependency (of the .1 file on
>>> the binary we run with --help) into a dependency on the .c file.
>>> * Makefile.am (do-not-require-help2man): New rule.
>>> (dist-hook): depend on it.
> ...
>> I believe this is incorrect.  Think of what happens if a user building from
>> the tarball modifies, say, 'src/ls.c', and then runs "make -j8" to rebuild
>> everything: make 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' ro 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' was
>> non-existent) or, worse, a man page with an up-to-date timestamp but an
>> out-of-date content.  And what's even worse is that this problem will be
>> present also for users who have perl installed!
>>
>> So we are breaking correctness for all tarball users only to accommodate
>> those few crippled systems lacking a decent perl.
>>
>> I think the right way to go is "graceful degradation": we should keep the
>> correct dependency for man pages ("man/ls.1: src/ls"); and if perl is not
>> present, we should use, instead of help2man, a shell script that just
>> emit a "placeholder" man page stating that a real man page couldn't be
>> built due to lack of perl, and redirecting the user back to either the
>> info documentation or the '--help' output.
>>
>> WDYT?
> 
> Hi Stefano,
> 
> Thanks for reviewing that.
> 
> I have mixed feelings.  If someone is modifying sources and expecting
> to be able to rebuild, they'd better have developer tools like perl.
>
Agreed.  And the major problem I see with your patch is exactly that it
could cause issues for savvy users on powerful systems having all the
required tools, just to cater to users on crippled systems.

> On the other hand, I dislike distributing a deliberately hamstrung
> Makefile.in, even though this wart is only in a generated file, that
> could easily be regenerated without the reduced dependency -- again,
> assuming proper tools.
>
> An added bonus of your approach: we would no longer need to distribute
> the man/*.1 files, and instead would generate them unconditionally, even
> from tarballs.
> 
> Do you feel like writing the patch, and especially documenting what
> would amount to a new, soft, build-from-tarball dependency on Perl?
>
I'd like to do that, but no promise about the time it will take (could
be one day, could be two weeks).

Thanks,
  Stefano