From 0700386f142f0b0d3d0021995970a1b41c36cc92 Mon Sep 17 00:00:00 2001 From: Andrew Burgess Date: Wed, 8 May 2024 19:12:57 +0100 Subject: 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 --- gdb/doc/Makefile.in | 50 +++++++++++++++----------------------------------- 1 file changed, 15 insertions(+), 35 deletions(-) diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index cfd3b35..cf10868 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) -- cgit v1.1