[commit: ghc] master: Add another chapter to the hi-rule novel (8a6b565)

[Ian Lynagh]

Repository : ssh://darcs.haskell.org//srv/darcs/ghc

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/8a6b56549ea12be736c47172d3cbeba9dc667918

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

commit 8a6b56549ea12be736c47172d3cbeba9dc667918
Author: Ian Lynagh <ian at well-typed.com>
Date:   Fri Feb 22 23:47:26 2013 +0000

    Add another chapter to the hi-rule novel

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

 rules/hi-rule.mk |   20 +++++++++++++++++++-
 1 files changed, 19 insertions(+), 1 deletions(-)

diff --git a/rules/hi-rule.mk b/rules/hi-rule.mk
index a343389..b87e600 100644
--- a/rules/hi-rule.mk
+++ b/rules/hi-rule.mk
@@ -67,9 +67,27 @@
 # However, given that rule, make thinks that it can make .hi files
 # for any object file, even if the object file was created from e.g.
 # a C source file. We therefore also add a dependency on the .hs/.lhs
-# source file, which means we finally end up with rules like:
+# source file, which means we end up with rules like:
 #
 # a/%.hi : a/%.o b/%.hs ;
+#
+# But! If a file is not explicitly mentioned in a makefile, then if
+# make needs to build it using such a %-rule then it treats it as an
+# 'intermediate file', and deletes it when it is finished. Most .hi
+# files are mentioned in .depend* files, as some other module depends on
+# them, but there are some library modules that aren't imported by
+# anything in the tree.
+#
+# We could stop make from deleting the .hi files by declaring
+# ".SECONDARY:", but if we do that then make takes a pathologically long
+# time with our build system. So we now generate (by calling hi-rule
+# from .depend* files) rules that look like
+#
+# a/B.hi a/B.dyn_hi : %hi : %o x/B.hs
+#
+# Now all the .hi files are explicitly mentioned in the makefiles, so
+# make doesn't think they are merely intermediate files, and doesn't
+# delete them.
 
 ifeq "$(ExtraMakefileSanityChecks)" "NO"