Re: [PATCH 4/5 v3] newlib: move man page generation into top-level build

Mike Frysinger <[email protected]> Tue, 1 Feb 2022 18:12:17 -0500
Newsgroups	gmane.comp.lib.newlib
Message-ID	<Yfm+UaxukIDTwbGb@vapier>
On 01 Feb 2022 14:37, Jon Turney wrote:
> On 01/02/2022 06:21, Mike Frysinger wrote:
> > +%D%/libc.xml.stamp: %D%/libc.in.xml $(LIBC_CHAPTERS) $(LIBC_DOCBOOK_OUT_FILES)
> > +	$(AM_V_at)\
> > +	for chapter in $(LIBC_CHAPTERS); do \
> > +	  $(TEXI2DOCBOOK) < $(srcdir)/$$chapter > %D%/`basename $${chapter%.tex}`.xml || exit 1; \
> > +	done
> > +	$(AM_V_GEN)xsltproc --xinclude --path $(builddir)/%D% --nonet $(srcdir)/refcontainers.xslt $< > [email protected]
> > +	$(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change [email protected] $(@:.stamp=)
> > +	$(AM_V_at)touch $@
> > +%D%/libc.xml: %D%/libc.xml.stamp; @true
> 
> This doesn't seem right.
> 
> This rule produces a single output with a definite name 'lib.xml', so 
> there's no need for a timestamp file?

you can use this exact same argument for targetdep.tex.  i don't see why we'd
use the stamp idiom for one but not the other.  they both gather multiple
inputs and produce a single output.  i'm fine killing off the stamp logic
entirely and changing move-if-change to a plain mv, and skipping the minor
timestamp optimization altogether.  we obviously don't write directly to $@
in order to avoid an interrupt producing an incomplete file that the build
cannot recover itself.

the older rules that i'm replacing had more expensive checks for their inputs
(using recursive makes and recursive stamps), but by merging the Makefiles
all into one, we have full direct visibility into all the inputs.  but that
aspect doesn't matter to what these specific stamp files are saving: keeping
timestamp shifts from forcing info & pdf & html & man regens.

afaict, the only arguments for this are (1) dev time optimization (building
from git) and (2) release time requirements (toolchain builders don't need
full texinfo stack as the dist tarball includes the info/pdf/etc...).  the
stamp files gets us (1) but not (2) because the newlib dists have never had
the docs included.  i think it's just a tarball of the git state.

old rules:

targetdep.tex: stmp-targetdep ; @true
stmp-targetdep: force
    rm -f tmp.texi
    targetdoc=`pwd`/tmp.texi; \
    for d in $(SUBDIRS); do \
      if test "$$d" != "."; then \
        (cd $$d && $(MAKE) doc) || exit 1; \
      fi; \
    done
    $(SHELL) $(newlib_basedir)/../move-if-change tmp.texi targetdep.tex
    touch $@

man: math/stmp-xml complex/stmp-xml libm.in.xml
    xsltproc --xinclude --path ${builddir} --nonet ${srcdir}/../refcontainers.xslt ${srcdir}/libm.in.xml >libm.xml
    ...
docbook-recursive: force
    for d in $(SUBDIRS); do \
      if test "$$d" != "."; then \
        (cd $$d && $(MAKE) docbook) || exit 1; \
      fi; \
    done
math/stmp-xml complex/stmp-xml: docbook-recursive

new rules don't have any recursive makes:

LIBM_CHAPTERS = <complete list of source .tex files>
%D%/targetdep.tex: $(LIBM_CHAPTERS)
    $(AM_V_GEN)cat $^ > [email protected]
    $(AM_V_at)mv [email protected] $@

LIBM_DOCBOOK_OUT_FILES = <complete list of generated .c -> .def -> .xml files>
%D%/libm.xml: %D%/libm.in.xml $(LIBM_CHAPTERS) $(LIBM_DOCBOOK_OUT_FILES)
    $(AM_V_at)\
    for chapter in $(LIBM_CHAPTERS); do \
      $(TEXI2DOCBOOK) < $(srcdir)/$$chapter > %D%/`basename $${chapter%.tex}`.xml || exit 1; \
    done
    $(AM_V_GEN)xsltproc --xinclude --path $(builddir)/%D% --nonet $(srcdir)/refcontainers.xslt $< > [email protected]
    $(AM_V_at)$(SHELL) $(newlib_basedir)/../move-if-change [email protected] $@
    $(AM_V_at)touch $@
-mike
signature.asc (application/pgp-signature, 833 B)