Re: Makefile logic to create Guix documentation

[Julien Lepiller]

Le 13 juin 2020 20:48:21 GMT-04:00, Chris Marusich <cmmarusich@gmail.com> a 
écrit :
>Hi Ludo,
>
>I was reading through the Makefile that creates the documentation, and
>I
>came across some parts I couldn't understand, even though I spent a few
>hours trying to figure it out.  I thought you might know the answers to
>my questions off the top of your head, since I think you wrote it.
>
>First, consider this snippet from doc/local.mk:
>
>--8<---------------cut here---------------start------------->8---
># We cannot add new dependencies to `%D%/guix.pdf' & co. (info
>"(automake)
># Extending").  Using the `-local' rules is imperfect, because they may
>be
># triggered after the main rule.  Oh, well.
>pdf-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.pdf)
>info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png)
>ps-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps)               \
>         $(top_srcdir)/%D%/images/coreutils-size-map.eps
>dvi-local: ps-local
>--8<---------------cut here---------------end--------------->8---
>
>What is this syntax called?  I checked the Make, Automake, and Autoconf
>manuals, but I couldn't find anything.  I'm talking about this syntax:
>
>  info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png)
>
>It looks like when you added this, you intended to add a *.png
>prerequisite to the info-local target for every equivalent *.dot file
>that exists.  My guess is you want to ensure that the PNG files are
>generated before the info page gets created, since the PNG files are
>required in order to build the info page.  However, is it possible you
>meant to write it like the following instead?  (The first "=" has been
>replaced with a ":".)
>
>  info-local: $(DOT_FILES:%.dot=$(top_srcdir)/%.png)
>                         
>When using ":", I recognize this syntax as a "substitution reference"
>(see: (make) Substitution Refs).  However, I do not know what it is
>supposed to be when the ":" is replaced with a "=".  Is it a typo?
>
>I experimented by adding a snippet like the following to the generated
>Makefile...
>
>--8<---------------cut here---------------start------------->8---
>marucustom: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps)
>       @echo XXXXX expansion is: _$(DOT_FILES=%.dot=$(top_srcdir)/%.eps)_
>       @echo XXXXX prerequisite: $<
>       @echo XXXXX target: $@
>--8<---------------cut here---------------end--------------->8---
>
>...and it seems to cause make to substitute an empty string:
>
>--8<---------------cut here---------------start------------->8---
>$ make marucustom
>XXXXX expansion is: __
>XXXXX prerequisite:
>XXXXX target: marucustom
>--8<---------------cut here---------------end--------------->8---
>
>Second, I noticed some rules like the following:
>
>--8<---------------cut here---------------start------------->8---
>.dot.eps:
>       $(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \
>       mv "$(srcdir)/$@.tmp" "$(srcdir)/$@"
>--8<---------------cut here---------------end--------------->8---
>
>What I do understand is that AM_V_DOT and DOT are set in Makefile.am
>and
>configure.ac, and that they are used to invoke the "dot" program.
>However, I couldn't quite understand the rest of this rule.
>
>Why are there no prerequisites?  It looks like the rule doesn't declare
>any prerequisites, so I'm confused about why the recipe includes
>references to the name of the first prerequisite ("$<").
>
>What causes this rule to be run?  I tried adding echo commands in the
>recipe like so...
>
>--8<---------------cut here---------------start------------->8---
>.dot.eps:
>       @echo YYYYY .dot.eps is running
>       @echo YYYYY target: %@
>       @echo YYYYY prerequisite: _$<_
>       $(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \
>       mv "$(srcdir)/$@.tmp" "$(srcdir)/$@"
>--8<---------------cut here---------------end--------------->8---
>
>...but I didn't see new messages when I ran "make" (from a clean
>checkout).  Maybe I didn't invoke make correctly.
>
>If you or anyone else could point out if I'm missing something, that'd
>be really helpful.  Thank you in advance!

Not sure for the rest, but .dot.eps: is similar to:

%.eps: %.dot

You often find .c.o in Makefiles for instance.