Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

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.
  • Loading branch information...
commit 093c87f98cd9b2497adc781c7415a4793df32c08 1 parent f4e534f
@simonmar simonmar authored
Showing with 66 additions and 16 deletions.
  1. +66 −16 rules/distdir-way-opts.mk
View
82 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 \
Please sign in to comment.
Something went wrong with that request. Please try again.