parallel build bug in git M4

[Ralf Wildenhues]

Hi Eric, all,

if my second patch for parallel build in GNUmakefile from this mail
<http://thread.gmane.org/gmane.comp.sysutils.automake.bugs/4476>
gets accepted into gnulib, then git master M4 will have a build bug, in
that an update of a build tree may fail due to the rule for the manpage.
More precisely, there are two issues:

The rule to update m4$(EXEEXT) is not atomic (which is ok for the rule
itself, but not for the m4.1 rule).  The first thing it does is remove
an old executable; so even when the re-creation of it happens to be
atomic (it may not be; but testing for executability may be sufficient
for the second part of the rule), the whole rule won't be.  This is
relevant, because the rule for m4.1 tests for existence of the
m4$(EXEEXT).

Also, testing for existence of m4$(EXEEXT) is not sufficient.  A
parallel build may be in the process of updating one of the libraries
that the program depends upon, while the m4.1 rule is run.  This can
cause an error from help2man.

I have been thinking about this a bit, and the only real solution that
I've found that doesn't involve other races or adding .NOTPARALLEL was
to reintroduce a subdir makefile.  But then we can put all doc/ rules
there again; see the patch below.  Do you see any other possibilities?

I should note that, on my system, this change does not slow down the
overall build time by much; the parallel build advantage is a lot
bigger.

Thanks,
Ralf

    Fix m4.1 build race, exposed by parallelism through GNUmakefile.
    
    * Makefile.am (SUBDIRS): Add doc.
    (Documentation rules): Move ...
    * doc/Makefile.am: ... to this new file.
    * configure.ac (AC_CONFIG_FILES): Generate doc/Makefile.

diff --git a/Makefile.am b/Makefile.am
index 01140c6..6e207a9 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -23,7 +23,7 @@
 config_aux_dir = build-aux
 config_macro_dir= ltdl/m4
 
-SUBDIRS                = po gnu . tests/gnu
+SUBDIRS                = po gnu . doc tests/gnu
 
 ACLOCAL_AMFLAGS = -I ltdl/m4
 AUTOMAKE_OPTIONS = nostdinc
@@ -245,38 +245,6 @@ dist-hook:
 EXTRA_DIST     += m4/system_.h
 
 
-## -------------- ##
-## Documentation. ##
-## -------------- ##
-
-info_TEXINFOS  = doc/m4.texinfo
-doc_m4_TEXINFOS        = doc/regexprops-generic.texi doc/fdl-1.3.texi 
doc/gpl-3.0.texi
-dist_man_MANS  = $(srcdir)/doc/m4.1
-EXTRA_DIST     += doc/gendocs_template
-MAINTAINERCLEANFILES += doc/gendocs_template
-HELP2MAN       = $(SHELL) $(srcdir)/$(config_aux_dir)/missing --run help2man
-
-# Build the man page once in the srcdir, rather than in every VPATH build
-# dir, to match how automake builds info pages.  This is safe for 'make
-# distcheck' since it is distributed pre-built.
-$(srcdir)/doc/m4.1: .version src/main.c
-       @if test -f src/m4$(EXEEXT); then \
-         echo "Updating the \`man' page \`$@'"; \
-         $(HELP2MAN) --name="macro processor" --source=FSF \
-           --info-page=m4 --output=$@ src/m4$(EXEEXT); \
-       else \
-         echo "WARNING: The \`man' page \`$@' cannot be updated yet."; \
-         echo "         Retry once the program executable is ready."; \
-       fi
-
-## Disabled for now.  Clashes with earlier definition.
-## TAGS_FILES  = $(infos_TEXINFOS)
-## TAGS_DEPENDENCIES = $(TAGS_FILES)
-## ETAGS_ARGS  = --language=none --regex='/@node \([^,]*\)/\1/' $(TAGS_FILES)
-
-MAINTAINERCLEANFILES += $(dist_man_MANS)
-
-
 ## --------- ##
 ## Examples. ##
 ## --------- ##
diff --git a/configure.ac b/configure.ac
index bb26ec3..766dd2d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -220,6 +220,7 @@ AM_CONDITIONAL([USE_GMP], [test "x$USE_GMP" = xyes])
 AC_CONFIG_FILES([
 Makefile
 gnu/Makefile
+doc/Makefile
 m4/system.h:m4/system_.h
 tests/atlocal
 tests/gnu/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..8d9a6fb
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,44 @@
+## Makefile.am - template for generating Makefile via Automake
+##
+## Copyright (C) 2009  Free Software Foundation, Inc.
+##
+## This file is part of GNU M4.
+##
+## GNU M4 is free software: you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## GNU M4 is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+MAINTAINERCLEANFILES =
+EXTRA_DIST =
+config_aux_dir = build-aux
+
+info_TEXINFOS  = m4.texinfo
+m4_TEXINFOS    = regexprops-generic.texi fdl-1.3.texi gpl-3.0.texi
+dist_man_MANS  = $(srcdir)/m4.1
+EXTRA_DIST     += gendocs_template
+MAINTAINERCLEANFILES += gendocs_template
+HELP2MAN       = $(SHELL) $(top_srcdir)/$(config_aux_dir)/missing --run 
help2man
+
+# Build the man page once in the srcdir, rather than in every VPATH build
+# dir, to match how automake builds info pages.  This is safe for 'make
+# distcheck' since it is distributed pre-built.
+$(srcdir)/m4.1: ../.version $(srcdir)/../src/main.c
+       @echo "Updating the \`man' page \`$@'"; \
+       $(HELP2MAN) --name="macro processor" --source=FSF \
+         --info-page=m4 --output=$@ ../src/m4$(EXEEXT)
+
+TAGS_FILES     = $(infos_TEXINFOS)
+TAGS_DEPENDENCIES = $(TAGS_FILES)
+ETAGS_ARGS     = --language=none --regex='/@node \([^,]*\)/\1/' $(TAGS_FILES)
+
+MAINTAINERCLEANFILES += $(dist_man_MANS)
+