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

[Mathieu Lirzin]

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 

> I'm using automake 1.15. I can't see anything since then that fixes this 
> problem.

Yes, this problem is likely to still be present in 1.16.1.

> The best workaround I could come up with was to revert the dependency to​
>
> ​ foo.1: foo$(EXEEXT)
>
> and then set distcleancheck_listfiles appropriately. Obviously, since
> this could hide other problems in the build system, it's not ideal.

This is not ideal since this result in making ‘help2man’ (and ‘perl’
transitively) a build dependency for tarball builders.

> Am I missing a better solution? If so, it should be added to the
> manual. If not, this problem should probably be documented. I'm
> finding that parallel make is becoming a must-have rather than a nice
> boost, given the proliferation of slow multi-core machines (for
> example: -j makes it feasible to hack on my phone; without it, builds
> are painfully slow).

I agree that it is important to provide a solution that support parallel
builds.  I remember that the issue has been adressed by Guix with
something like this (untested):

--8<---------------cut here---------------start------------->8---
$(srcdir)/foo.1: foo.c foo$(EXEEXT)
        address@hidden '$?' in \
          *foo.c*) $(AM_V_P) && set -x || echo "  HELP2MAN $@"; \
                   LANGUAGE= help2man --output="$(srcdir)/foo.1" 
./foo$(EXEEXT);; \
          *) : ;; \
        esac;
--8<---------------cut here---------------end--------------->8---

This solution handles silent rules and possible localization of the
‘./foo --help’ output.  However its limitation is that if you have
another rule with ‘$(srcdir)/foo.1’ as a prerequisite then it will be
triggered at every build.

WDYT?

Thanks for the report.

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