Re: [PATCHv3 6/6] gdb/doc: fix parallel build of pdf and dvi files

[Andrew Burgess <aburgess@redhat.com>]

Here's an updated version of just patch #6.  In this update:

  - Removed all the configure nonsense, we already require a version of
    texinfo greater than 4.9, so I just assume the required options are
    available.

  - Now also make use of the --build-dir option (also added in 4.9) to
    better control the creation of the temporary directories, this makes
    it easier to cleanup (see mostlyclean recipe).

Let me know what you think.

Thanks,
Andrew

---

commit e063bdc6f213f80da0de28a7f84cd31f240a6716
Author: Andrew Burgess <aburgess@redhat.com>
Date:   Wed May 8 19:12:57 2024 +0100

    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.

diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index cfd3b3597fb..cf10868ed05 100644
--- 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)