[Xen-devel] [PATCH for-4.7 1/3] docs/build: Avoid using multi-target pattern rules

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

Multi-target non-pattern rules and Multi-target pattern rules behave rather
differently.  From `Pattern Intro':

  Pattern rules may have more than one target.  Unlike normal rules, this does
  not act as many different rules with the same prerequisites and commands.
  If a pattern rule has multiple targets, `make' knows that the rule's
  commands are responsible for making all of the targets.  The commands are
  executed only once to make all the targets.

The intended use of the multi-target pattern rules was to avoid repeating the
identical recipe multiple times.  The issue can be demonstrated with the
generation of documentation from pandoc source.

  ./xen.git$ touch docs/features/template.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>
Acked-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
Release-acked-by: 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