[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

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

  target1 target2: prereq

is equivilent to

  target1: prereq
  target2: prereq

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

  ./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

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 $@
-       @echo "pandoc not installed; skipping $@"
+# Metarule for generating pandoc rules.
+# $(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 $$@
-       @echo "pandoc not installed; skipping $@"
+       @echo "pandoc not installed; skipping $$@"
+$(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)))
        $(error You have to run ./configure before building docs)

Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.