Add another chapter to the hi-rule novel

1 files changed, 19 insertions, 1 deletions

diff --git a/rules/hi-rule.mk b/rules/hi-rule.mk
index a343389967..b87e600990 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"