Makefile logic to create Guix documentation

[Chris Marusich <cmmarusich@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3945 bytes --]

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!

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]