1 files changed, 51 insertions, 0 deletions
diff --git a/docs/comm/genesis/makefiles.html b/docs/comm/genesis/makefiles.html
new file mode 100644
index 0000000000..957a82eb85
--- /dev/null
+++ b/docs/comm/genesis/makefiles.html
@@ -0,0 +1,51 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+  <head>
+    <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+    <title>The GHC Commentary - Mindboggling Makefiles</title>
+  </head>
+
+  <body BGCOLOR="FFFFFF">
+    <h1>The GHC Commentary - Mindboggling Makefiles</h1>
+    <p>
+      The size and structure of GHC's makefiles makes it quite easy to scream
+      out loud - in pain - during the process of tracking down problems in the
+      make system or when attempting to alter it.  GHC's <a
+	href="http://haskell.cs.yale.edu/ghc/docs/latest/building/building-guide.html">Building
+	Guide</a> has valuable information on <a
+	href="http://haskell.cs.yale.edu/ghc/docs/latest/building/sec-makefile-arch.html">the
+	makefile architecture.</a>
+
+    <h4>A maze of twisty little passages, all alike</h4>
+    <p>
+      The <code>fptools/</code> toplevel and the various project directories
+      contain not only a <code>Makefile</code> each, but there are
+      subdirectories of name <code>mk/</code> at various levels that contain
+      rules, targets, and so on specific to a project - or, in the case of the
+      toplevel, the default rules for the whole system.  Each <code>mk/</code>
+      directory contains a file <code>boilerplate.mk</code> that ties the
+      various other makefiles together.  Files called <code>target.mk</code>,
+      <code>paths.mk</code>, and <code>suffix.mk</code> contain make targets,
+      definitions of variables containing paths, and suffix rules,
+      respectively.
+    <p>
+      One particularly nasty trick used in this hierarchy of makefiles is the
+      way in which the variable <code>$(TOP)</code> is used.  AFAIK,
+      <code>$(TOP)</code> always points to a directory containing an
+      <code>mk/</code> subdirectory; however, it not necessarily points to the
+      toplevel <code>fptools/</code> directory.  For example, within the GHC
+      subtree, <code>$(TOP)</code> points to <code>fptools/ghc/</code>.
+      However, some of the makefiles in <code>fptools/ghc/mk/</code> will then
+      <em>temporarily</em> redefine <code>$(TOP)</code> to point a level
+      higher (i.e., to <code>fptools/</code>) while they are including the
+      toplevel boilerplate.  After that <code>$(TOP)</code> is redefined to
+      whatever value it had before including makefiles from higher up in the
+      hierarchy. 
+
+    <p><small>
+<!-- hhmts start -->
+Last modified: Wed Aug 22 16:46:33 GMT Daylight Time 2001
+<!-- hhmts end -->
+    </small>
+  </body>
+</html>