[Xen-changelog] [xen master] docs/build: Avoid using multi-target pattern rules

[patchbot@xxxxxxx]

commit e9bcfcfbde744fea656556b09e35f798144d0bbc
Author:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
AuthorDate: Mon Apr 25 12:55:12 2016 +0000
Commit:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CommitDate: Mon May 23 11:22:42 2016 +0100

    docs/build: Avoid using multi-target pattern rules
    
    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)
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog