gdb/doc: fix parallel build of pdf and dvi files

When building with 'make -j20 -C gdb/doc all-doc' I often see problems
caused from trying to build some dvi files in parallel with some pdf
files.  The problem files are: gdb.dvi and gdb.pdf; stabs.dvi and
stabs.pdf; and annotate.dvi and annotate.pdf.

The problem is that building these files create temporary files in the
local directory.  There's already a race here that two make threads
might try to create these files at the same time.

But it gets worse, to avoid issues where a failed build could leave
these temporary files in a corrupted state, and so prevent the next
build from succeeding, the recipe for each of these files deletes all
the temporary files first, this obviously causes problems if some
other thread has already started the build and is relying on these
temporary files.

To work around this problem I propose we start using the --build and
--build-dir options for texi2dvi (which is the same tool used to
create the pdf files).  These options were added in texinfo 4.9 which
was released in June 2007.  We already require using a version of
texinfo after 4.9 (I tried to build with 4.13 and the doc build failed
as some of the texinfo constructs were not understood), so this patch
has not changed the minimum required version at all.

The --build flag allows the temporary files to be placed into a
sub-directory, and the --build-dir option allows us to control the
name of that sub-directory.

What we do is create a unique sub-directory for each target that
invokes texi2dvi, all of the unique sub-directories are created within
a single directory texi2dvi_tmpdir, and so after a complete doc build,
we are left with a build tree like this:

  build/gdb/doc/
  '-- texi2dvi_tmpdir/
      |-- annotate_dvi/
      |-- annotate_pdf/
      |-- gdb_dvi/
      |-- gdb_pdf/
      |-- stabs_dvi/
      '-- stabs_pdf/

I've left out all the individual files that live within these
directories for simplicity.

To avoid corrupted temporary files preventing a future build to
complete, each recipe deletes its associated sub-directory from within
texi2dvi_tmpdir/ before it attempts a build, this ensures a fresh
start each time.

And the mostlyclean target deletes texi2dvi_tmpdir/ and all its
sub-directories, ensuring that everything is cleaned up.

For me, with this fix in place, I can now run 'make -j20 -C gdb/doc
all-doc' without seeing any build problems.

Approved-By: Pedro Alves <pedro@palves.net>

diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index cfd3b3597fb55f4c7f1d9a4c9a08a95f0ed02cff..cf10868ed058b05a31baee841737024b23c1d24e 100644 (file)
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -66,8 +66,13 @@ MAKEHTMLFLAGS =
 # where to find texi2roff, ditto
 TEXI2ROFF=texi2roff
 
-# where to find texi2dvi, ditto
+# Where to find texi2dvi.  The use of --build and --build-dir options
+# mean that at least texinfo 4.9 is required.
 TEXI2DVI=texi2dvi
+TEXI2DVI_TMPDIR=texi2dvi_tmpdir
+TEXI2DVI_CMD = rm -fr $(TEXI2DVI_TMPDIR)/$(subst .,_,$@) \
+               && $(TEXI2DVI) --build=tidy \
+                              --build-dir=$(TEXI2DVI_TMPDIR)/$(subst .,_,$@)
 
 # Package to install the docs under
 PACKAGE = @PACKAGE@
@@ -481,24 +486,17 @@ gdb-cfg.texi: ${srcdir}/${DOC_CONFIG}-cfg.texi
        ln ${srcdir}/${DOC_CONFIG}-cfg.texi gdb-cfg.texi || \
        cp ${srcdir}/${DOC_CONFIG}-cfg.texi gdb-cfg.texi
 
-# Clean these up before each run.  Avoids a catch 22 with not being
-# able to re-generate these files (to fix a corruption) because these
-# files contain a corruption.
-GDB_TEX_TMPS = gdb.aux gdb.cp* gdb.fn* gdb.ky* gdb.log gdb.pg* gdb.toc \
-       gdb.tp* gdb.vr*
-
 # GDB MANUAL: TeX dvi file
 gdb.dvi: ${GDB_DOC_FILES}
-       $(SILENCE) rm -f $(GDB_TEX_TMPS)
-       $(ECHO_TEXI2DVI) $(TEXI2DVI) $(SILENT_Q_FLAG) $(READLINE_TEXI_INCFLAG) \
-               -I ${GDBMI_DIR} -I $(srcdir) $(srcdir)/gdb.texinfo
+       $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) \
+               $(READLINE_TEXI_INCFLAG) -I ${GDBMI_DIR} -I $(srcdir) \
+               $(srcdir)/gdb.texinfo
 
 gdb.ps: gdb.dvi
        $(ECHO_DVIPS) $(DVIPS) $(SILENT_Q_FLAG) -o $@ $?
 
 gdb.pdf: ${GDB_DOC_FILES}
-       $(SILENCE) rm -f $(GDB_TEX_TMPS)
-       $(ECHO_TEXI2DVI) $(TEXI2DVI) $(SILENT_Q_FLAG) --pdf \
+       $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) --pdf \
                $(READLINE_TEXI_INCFLAG) -I ${GDBMI_DIR} -I $(srcdir) \
                $(srcdir)/gdb.texinfo
 
@@ -596,44 +594,28 @@ stabs/index.html: $(STABS_DOC_FILES)
                -I $(srcdir) \
                $(srcdir)/stabs.texinfo
 
-# Clean these up before each run.  Avoids a catch 22 with not being
-# able to re-generate these files (to fix a corruption) because these
-# files contain a corruption.
-STABS_TEX_TMPS = stabs.aux stabs.cp* stabs.fn* stabs.ky* \
-       stabs.log stabs.pg* stabs.toc stabs.tp* stabs.vr*
-
 # STABS DOCUMENTATION: TeX dvi file
 stabs.dvi : $(STABS_DOC_FILES)
-       $(SILENCE) rm -f $(STABS_TEX_TMPS)
-       $(ECHO_TEXI2DVI) $(TEXI2DVI) $(SILENT_Q_FLAG) -I $(srcdir) \
+       $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) -I $(srcdir) \
                $(srcdir)/stabs.texinfo
 
 stabs.ps: stabs.dvi
        $(ECHO_DVIPS) $(DVIPS) $(SILENT_Q_FLAG) -o $@ $?
 
 stabs.pdf: $(STABS_DOC_FILES)
-       $(SILENCE) rm -f $(STABS_TEX_TMPS)
-       $(ECHO_TEXI2DVI) $(TEXI2DVI) $(SILENT_Q_FLAG) --pdf -I $(srcdir) \
+       $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) --pdf -I $(srcdir) \
                $(srcdir)/stabs.texinfo
 
-# Clean these up before each run.  Avoids a catch 22 with not being
-# able to re-generate these files (to fix a corruption) because these
-# files contain a corruption.
-ANNOTATE_TEX_TMPS = annotate.aux annotate.cp* annotate.fn* annotate.ky* \
-       annotate.log annotate.pg* annotate.toc annotate.tp* annotate.vr*
-
 # ANNOTATE DOCUMENTATION: TeX dvi file
 annotate.dvi : $(ANNOTATE_DOC_FILES)
-       $(SILENCE) rm -f $(ANNOTATE_TEX_TMPS)
-       $(ECHO_TEXI2DVI) $(TEXI2DVI) $(SILENT_Q_FLAG) -I $(srcdir) \
+       $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) -I $(srcdir) \
                $(srcdir)/annotate.texinfo
 
 annotate.ps: annotate.dvi
        $(ECHO_DVIPS) $(DVIPS) $(SILENT_Q_FLAG) -o $@ $?
 
 annotate.pdf: $(ANNOTATE_DOC_FILES)
-       $(SILENCE) rm -f $(ANNOTATE_TEX_TMPS)
-       $(ECHO_TEXI2DVI) $(TEXI2DVI) $(SILENT_Q_FLAG) --pdf -I $(srcdir) \
+       $(ECHO_TEXI2DVI) $(TEXI2DVI_CMD) $(SILENT_Q_FLAG) --pdf -I $(srcdir) \
                $(srcdir)/annotate.texinfo
 
 annotate.info: $(ANNOTATE_DOC_FILES)
@@ -683,9 +665,7 @@ Makefile: Makefile.in $(host_makefile_frag) ../config.status
 
 mostlyclean:
        rm -f gdb.mm gdb.ms gdb.me links2roff
-       rm -f $(GDB_TEX_TMPS)
-       rm -f $(STABS_TEX_TMPS)
-       rm -f $(ANNOTATE_TEX_TMPS)
+       rm -fr $(TEXI2DVI_TMPDIR)
        rm -f refcard.sed sedref.tex sedref_dvi.* sedref_pdf.*
        rm -f $(POD_FILE_TMPS)