Build system commentary

Add documentation describing all the variables that contain options
for Haskell compilations, what they mean and where they are (or can
be) defined.

In due course we should expand this to cover all the build system
variables, and move it to the wiki, but this is a start.

rules/distdir-way-opts.mk

@@ -15,21 +15,67 @@
 
 define distdir-way-opts # args: $1 = dir, $2 = distdir, $3 = way, $4 = stage
 
-# Options for a Haskell compilation:
-#   - CONF_HC_OPTS                 source-tree-wide options, selected at
-#                                  configure-time
-#   - SRC_HC_OPTS                  source-tree-wide options from build.mk
-#                                  (optimisation, heap settings)
-#   - libraries/base_HC_OPTS       options from Cabal for libraries/base
-#                                  for all ways
-#   - libraries/base_MORE_HC_OPTS  options from elsewhere in the build
-#                                  system for libraries/base for all ways
-#   - libraries/base_v_HC_OPTS     options from libraries/base for way v
-#   - WAY_v_HC_OPTS                options for this way
-#   - EXTRA_HC_OPTS                options from the command-line
-#   - -Idir1 -Idir2 ...            include-dirs from this package
-#   - -odir/-hidir/-stubdir        put the output files under $3/build
-#   - -osuf/-hisuf/-hcsuf          suffixes for the output files in this way
+# Here is how the command line for a Haskell compilation is constructed.
+#   $1 is the directory we're building in
+#   $2 is the distdir (e.g. "dist", "dist-install" etc.)
+#   $3 is the way (e.g. "v", "p", etc.)
+#   $4 is the stage ("1", "2", "3")
+# 
+# -----------------------------
+# The variables affecting Haskell compilations are as follows, including
+# the places in the build system that may define them.
+#
+#  Variable              Purpose                           Defined by
+#  --------------        ------------------------------    --------------
+#  $1_PACKAGE            Package name for this dir,        $1/$2/ghc.mk
+#                        if it is a package		   
+#							   
+#  CONF_HC_OPTS          GHC options from ./configure      mk/config.mk.in
+#							   
+#  CONF_HC_OPTS_STAGE$4  GHC options from ./configure      mk/config.mk.in
+#                        specific to stage $4		   
+#							   
+#  WAY_$3_HC_OPTS        GHC options specific to way $3    mk/ways.mk
+#							   
+#  SRC_HC_OPTS           source-tree-wide GHC options      mk/config.mk.in
+#                                                          mk/build.mk
+#                                                          mk/validate.mk
+#							   
+#  EXTRA_HC_OPTS         for supplying extra options on    make EXTRA_HC_OPTS=...
+#                        the command line		   
+#							   
+#  $1_HC_OPTS            GHC options specific to this      $1/$2/package-data.mk
+#                        dir
+#							   
+#  $1_$2_HC_OPTS         GHC options specific to this      $1/$2/package-data.mk
+#                        dir and distdir
+#							   
+#  $1_$2_$3_HC_OPTS      GHC options specific to this      $1/$2/package-data.mk
+#                        dir, distdir and way
+#							   
+#  $1_$2_MORE_HC_OPTS    GHC options for this dir/distdir  ???
+#							   
+#  $1_$2_EXTRA_HC_OPTS   GHC options for this dir/distdir  mk/build.mk
+#							   
+#  $1_$2_HC_PKGCONF      -package-conf flag if necessary   rules/package-config.mk
+#							   
+#  $1_$2_HS_SRC_DIRS     dirs relative to $1 containing    $1/$2/package-data.mk
+#                        source files			   
+#							   
+#  $1_$2_CPP_OPTS        CPP options                       $1/$2/package-data.mk
+#  
+#  <file>_HC_OPTS        GHC options for this source       $1/$2/ghc.mk
+#                        file (without the extension)
+
+# -----------------------------
+
+# The actual options passed to a Haskell compilation are defined
+# below.  Note that in general, more specific sets of options come
+# after the less specific, so that we can override global options
+# on a per-directory or per-way basis, for example.
+
+# $1_$2_$3_MOST_HC_OPTS is also passed to C compilations when we use
+# GHC as the C compiler.
 
 $1_$2_$3_MOST_HC_OPTS = \
  $$(WAY_$3_HC_OPTS) \
@@ -58,7 +104,11 @@ $1_$2_$3_MOST_HC_OPTS = \
  $$($$(basename $$<)_HC_OPTS) \
  $$(EXTRA_HC_OPTS)
 
-# For real Haskell compilations we add -hidir etc.
+# NB. CONF_HC_OPTS_STAGE$4 has to be late enough to override $1_$2_HC_OPTS, so
+# that -O0 is effective (see #5484)
+
+# $1_$2_$3_ALL_HC_OPTS: this is all the options we will pass to GHC
+# for a given ($1,$2,$3).
 $1_$2_$3_ALL_HC_OPTS = \
  $$($1_$2_$3_MOST_HC_OPTS) \
  -odir $1/$2/build -hidir $1/$2/build -stubdir $1/$2/build \