[commit: ghc] master: ghc.mk: don't run mkUserGuidePart more than once (d6512c7)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/d6512c740c653d2a58a7fc73b777e50d02f786b1/ghc

>---------------------------------------------------------------

commit d6512c740c653d2a58a7fc73b777e50d02f786b1
Author: Sergei Trofimovich <siarheit at google.com>
Date:   Sat Dec 5 00:03:05 2015 +0000

    ghc.mk: don't run mkUserGuidePart more than once
    
    When building 'html' and 'man' manuals
    build system reports mkUserGuide is ran
    more than once (up to 3 times in parallel).
    
    See Note [Blessed make target file] for
    more details.
    
    Signed-off-by: Sergei Trofimovich <siarheit at google.com>


>---------------------------------------------------------------

d6512c740c653d2a58a7fc73b777e50d02f786b1
 utils/mkUserGuidePart/ghc.mk | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/utils/mkUserGuidePart/ghc.mk b/utils/mkUserGuidePart/ghc.mk
index 86492e1..3a654da 100644
--- a/utils/mkUserGuidePart/ghc.mk
+++ b/utils/mkUserGuidePart/ghc.mk
@@ -39,11 +39,18 @@ utils/mkUserGuidePart_GENERATED_FLAGS_SETS := \
   verbosity                   \
   warnings
 
-utils/mkUserGuidePart_GENERATED_RST_SOURCES := \
+# See Note [Blessed make target file]
+utils/mkUserGuidePart_GENERATED_RST_SOURCES_BLESSED_FILE := \
+		docs/users_guide/what_glasgow_exts_does.gen.rst
+
+utils/mkUserGuidePart_GENERATED_RST_SOURCES_OTHER_FILES := \
 		$(addprefix docs/users_guide/flags-,$(addsuffix .gen.rst,$(utils/mkUserGuidePart_GENERATED_FLAGS_SETS))) \
-		docs/users_guide/what_glasgow_exts_does.gen.rst \
 		docs/man/all-flags.gen.rst
 
+utils/mkUserGuidePart_GENERATED_RST_SOURCES := \
+		$(utils/mkUserGuidePart_GENERATED_RST_SOURCES_BLESSED_FILE) \
+		$(utils/mkUserGuidePart_GENERATED_RST_SOURCES_OTHER_FILES)
+
 utils/mkUserGuidePart_USES_CABAL           = YES
 utils/mkUserGuidePart_PACKAGE              = mkUserGuidePart
 utils/mkUserGuidePart_dist_PROGNAME        = mkUserGuidePart
@@ -52,7 +59,36 @@ utils/mkUserGuidePart_dist_INSTALL_INPLACE = YES
 $(eval $(call build-prog,utils/mkUserGuidePart,dist,2))
 $(eval $(call clean-target,utils/mkUserGuidePart,gen,$(utils/mkUserGuidePart_GENERATED_RST_SOURCES)))
 
-$(utils/mkUserGuidePart_GENERATED_RST_SOURCES) : $(mkUserGuidePart_INPLACE)
+$(utils/mkUserGuidePart_GENERATED_RST_SOURCES_OTHER_FILES) :
+
+$(utils/mkUserGuidePart_GENERATED_RST_SOURCES_BLESSED_FILE) : $(utils/mkUserGuidePart_GENERATED_RST_SOURCES_OTHER_FILES) $(mkUserGuidePart_INPLACE)
 	$(mkUserGuidePart_INPLACE)
+	$(TOUCH_CMD) $@
 
 all_utils/mkUserGuidePart: $(mkUserGuidePart_INPLACE)
+
+# Note [Blessed make target file]
+#
+# make cannot express nicely a single build rule
+# with multiple targets:
+#
+#   > all: a b
+#   > a b:
+#   > 	touch a b
+#
+# This code will run 'touch' rule twice when parallel
+# make is used:
+#   > $ make -j
+#   > touch a b
+#   > touch a b
+#
+# But there is a workaround for it:
+# We pick a single file of a group and depend on it
+# as an ultimate target. We also need to make sure
+# that file has latest timestamp in the group:
+#
+#   > all: a b
+#   > b:
+#   > a: b
+#   > 	touch a b
+#   > 	touch $@