bug#31157: Advice for help2man does not work for parallel builds

[Mathieu Lirzin]

Hello Peter,

Peter Johansson <address@hidden> writes:

> On 4/22/2018 1:13 AM, Mathieu Lirzin wrote:
>> Hello Reuben,
>>
>> Reuben Thomas <address@hidden> writes:
>>
>>> In the manual, we are given the following pattern for using help2man
>>> without breaking make distcheck:
>>>
>>> foo.1: foo.c $(top_srcdir)/configure.ac
>>> $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
>>> help2man --output=foo.1 ./foo$(EXEEXT)
>>>
>>> The problem is that with make -j this can result in two attempts to
>>> make a library in parallel (suppose that we have:
>>>
>>> foo_LDADD = libfoo.la
>>> lib_LTLIBRARIES = libfoo.la
>>>
>>> ). This can fail, and in any case is wasteful.
>> Have you identified the reason why this can fail?  because
>
> One problem is that the rule for foo.1 can be triggered before
> foo.$(EXEEXT) exists and the rule needs foo.$(EXEEXT) or help2man will
> fail. In a -j1 build this is never a problem as binaries are built
> before man pages.

with the ‘$(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)’ recipe line, normally
this ensures that the ‘foo$(EXEEXT)’ is built at least once.  My
question was about understanding why building a program/library twice
may end up in a failure in a parallel context.

The answer from Reuben was that since compilation is not thead safe when
for example deleting shared temporary files, then concurrent processes
might impact each other.

> When the 'missing' script changed behaviour in Automake 1.13 (and
> became useless imvho), we changed the rule in one project so foo.1
> depended on foo.$(EXEEXT) but not if we are 1) building from a tarball
> and 2) foo.$(EXEEXT) exists.
>
> http://dev.thep.lu.se/svndigest/browser/trunk/man/Makefile.am

This is an alternative solution which is used by GNU Hello too.  I
remember some people not being fond of this approach because of its
AM_MAINTAINER_MODE spirit [1].

[1] 
https://www.gnu.org/software/automake/manual/html_node/maintainer_002dmode.html

Thanks for your feedback.

-- 
Mathieu Lirzin
GPG: F2A3 8D7E EB2B 6640 5761  070D 0ADE E100 9460 4D37