[Xen-devel] [PATCH for-4.7] docs/build: Work around apparent bug with multi-target rules

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

The `make` manual documents that a rule of the form

  target1 target2: prereq
        recipe

is equivilent to

  target1: prereq
        recipe
  target2: prereq
        recipe

This is correct if only target1 or target2 is wanted, but is not the case if
both target1 and target2 are wanted to be rebuilt in the same pass.  In such a
case, executing the recipe to generate target1 causes the entire rule to be
considered complete, short circuiting the search to regenerate target2.

This bug can be demonstrated with the generation of documentation from pandoc
source.

  ./xen.git$ touch docs/features/templace.pandoc
  ./xen.git$ make -C docs/
  # Regenerates html/features/template.html
  ./xen.git$ make -C docs/
  # Regenerates txt/features/template.txt
  ./xen.git$ make -C docs/
  # Regenerates pdf/features/template.pdf

To work around this, there need to be three distinct rules, so the execution
of one recipe doesn't short ciruit the others.  To avoid copy&paste
duplication, introduce a metarule, and evalute it for each document target.

As $(PANDOC) is used to generate documentation from different source types,
the metarule can be extended to also encompas the rule to create pdfs from
markdown.

Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
---
CC: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
CC: Wei Liu <wei.liu2@xxxxxxxxxx>
---
 docs/Makefile | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index b9da605..e2537e8 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -180,22 +180,24 @@ txt/%.txt: %.markdown
        @$(INSTALL_DIR) $(@D)
        $(INSTALL_DATA) $< $@
 
-pdf/%.pdf: %.markdown
-ifneq ($(PANDOC),)
-       @$(INSTALL_DIR) $(@D)
-       $(PANDOC) --number-sections --toc --standalone $< --output $@
-else
-       @echo "pandoc not installed; skipping $@"
-endif
+# Metarule for generating pandoc rules.
+define GENERATE_PANDOC_RULE
+# $(1) is the target documentation format. $(2) is the source format.
 
-pdf/%.pdf txt/%.txt html/%.html: %.pandoc
+$(1)/%.$(1): %.$(2)
 ifneq ($(PANDOC),)
-       @$(INSTALL_DIR) $(@D)
-       $(PANDOC) --number-sections --toc --standalone $< --output $@
+       @$(INSTALL_DIR) $$(@D)
+       $(PANDOC) --number-sections --toc --standalone $$< --output $$@
 else
-       @echo "pandoc not installed; skipping $@"
+       @echo "pandoc not installed; skipping $$@"
 endif
 
+endef
+$(eval $(call GENERATE_PANDOC_RULE,pdf,pandoc))   # pdf/%.pdf: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,txt,pandoc))   # txt/%.txt: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,html,pandoc))  # html/%.html: %.pandoc
+$(eval $(call GENERATE_PANDOC_RULE,pdf,markdown)) # pdf/%.pdf: %.markdown
+
 ifeq (,$(findstring clean,$(MAKECMDGOALS)))
 $(XEN_ROOT)/config/Docs.mk:
        $(error You have to run ./configure before building docs)
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel