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

From: Mathieu Lirzin <[email-masked]>
Date: Sat, 21 Apr 2018 17:13:58 +0200

Hello Reuben,

Reuben Thomas <[email-masked]> 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)
	-@case '$?' 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