Build system: Add stage specific SRC_HC_(WARNING_)OPTS

* Add stage specific versions of SRC_HC_OPTS. These are currently only
  used for -Werror. The previous combination of GhcStage2HcOpts and
  GhcLibHcOpts didn't apply to utils/*.

* Add stage specific versions of SRC_HC_WARNING_OPTS. These will later be
  used for new warning supression flags that should not be passed to the
  bootstrap compiler.

* Move -Wall (and -Werror) related code back to mk/warnings.mk, where it
  was before 987d54274. Now all warning related code is nicely together.
  Include mk/warnings.mk after mk/custom-settings.mk to make this work.

Reviewed By: bgamari, hvr

Differential Revision: https://phabricator.haskell.org/D1536

5 files changed, 99 insertions, 37 deletions

diff --git a/ghc.mk b/ghc.mk
index caa903ddf1..9dd1c91b2b 100644
--- a/ghc.mk
+++ b/ghc.mk
@@ -138,21 +138,14 @@ endif
 endif
 
 include mk/ways.mk
-include mk/warnings.mk
 
 # (Optional) build-specific configuration
 include mk/custom-settings.mk
-SRC_CC_OPTS     += -Wall
-SRC_HC_OPTS     += -Wall
-# Don't add -Werror to GhcStage1HcOpts, because otherwise validate may
-# unnecessarily fail during the stage1 build when booting with an older
-# compiler.
-# It would be better to only exclude certain warnings from becoming errors
-# (e.g. '-Werror -Wno-error=unused-imports -Wno-error=...'), but -Wno-error
-# isn't supported yet (https://ghc.haskell.org/trac/ghc/wiki/Design/Warnings).
-SRC_CC_OPTS     += $(WERROR)
-GhcStage2HcOpts += $(WERROR)
-GhcLibHcOpts    += $(WERROR)
+
+# The user can reset SRC_HC_OPTS from mk/build.mk. Since we try to append
+# '-Wall' to it in mk/warnings.mk, we have to include mk/warnings.mk after
+# mk/custom-settings.mk.
+include mk/warnings.mk
 
 # -----------------------------------------------------------------------------
 # Check for inconsistent settings, after reading mk/build.mk.
diff --git a/mk/config.mk.in b/mk/config.mk.in
index f9394429bf..967c7510a1 100644
--- a/mk/config.mk.in
+++ b/mk/config.mk.in
@@ -64,10 +64,36 @@ GhcHcOpts=-Rghc-timing
 # Extra options added to specific stages of the compiler bootstrap.
 # These are placed later on the command line, and may therefore
 # override options from $(GhcHcOpts).
+#
+# See Note [Stage number in build variables].
 GhcStage1HcOpts=
 GhcStage2HcOpts=-O2
 GhcStage3HcOpts=-O2
 
+# Disable -O2 optimization. Otherwise amount of generated C code
+# makes things very slow to compile (~5 minutes on core-i7 for 'compiler/hsSyn/HsExpr.lhs')
+# and sometimes not compile at all (powerpc64 overflows something
+# on 'compiler/hsSyn/HsExpr.lhs').
+ifeq "$(GhcUnregisterised)" "YES"
+GhcStage1HcOpts=
+GhcStage2HcOpts=
+GhcStage3HcOpts=
+endif
+
+# Note [Stage number in build variables].
+#
+# There are (unfortunately) two different naming schemes for build variables
+# specific to a certain stage.
+#
+# * GhcStage1HcOpts/GhcStage2HcOpts/GhcStage3HcOpts:
+#
+#   The stage number refers to the compiler stage being built (ghc library
+#   and executable).
+#
+# * SRC_HC_OPTS_STAGE$4 and SRC_HC_WARNING_OPTS_STAGE$4:
+#
+#   The stage number refers to the compiler stage the options are passed to.
+
 GhcDebugged=NO
 GhcDynamic=NO
 
@@ -408,15 +434,20 @@ BIN_DIST_TAR_COMP     = $(BIN_DIST_NAME)-$(TARGETPLATFORM).tar.$(TAR_COMP_EXT)
 #
 SRC_HC_OPTS += -H32m -O
 
-# Disable -O2 optimization. Otherwise amount of generated C code
-# makes things very slow to compile (~5 minutes on core-i7 for 'compiler/hsSyn/HsExpr.lhs')
-# and sometimes not compile at all (powerpc64 overflows something
-# on 'compiler/hsSyn/HsExpr.lhs').
-ifeq "$(GhcUnregisterised)" "YES"
-GhcStage1HcOpts=
-GhcStage2HcOpts=
-GhcStage3HcOpts=
-endif
+
+# See Note [Stage number in build variables].
+SRC_HC_OPTS_STAGE0 =
+SRC_HC_OPTS_STAGE1 =
+SRC_HC_OPTS_STAGE2 =
+
+# Warning supression flags. See mk/warnings.mk.
+SRC_CC_WARNING_OPTS =
+SRC_HC_WARNING_OPTS =
+
+# See Note [Stage number in build variables].
+SRC_HC_WARNING_OPTS_STAGE0 =
+SRC_HC_WARNING_OPTS_STAGE1 =
+SRC_HC_WARNING_OPTS_STAGE2 =
 
 # -----------------------------------------------------------------------------
 # Names of programs in the GHC tree
diff --git a/mk/warnings.mk b/mk/warnings.mk
index 267aef6a36..d604f9ae2d 100644
--- a/mk/warnings.mk
+++ b/mk/warnings.mk
@@ -1,9 +1,16 @@
-SRC_CC_WARNING_OPTS =
-SRC_HC_WARNING_OPTS =
-
+# See Note [Order of warning flags].
+SRC_CC_OPTS     += -Wall $(WERROR)
+SRC_HC_OPTS     += -Wall
+# Don't add -Werror to SRC_HC_OPTS_STAGE0 (or SRC_HC_OPTS), because otherwise
+# validate may unnecessarily fail when booting with an older compiler.
+# It would be better to only exclude certain warnings from becoming errors
+# (e.g. '-Werror -Wno-error=unused-imports -Wno-error=...'), but -Wno-error
+# isn't supported yet (https://ghc.haskell.org/trac/ghc/wiki/Design/Warnings).
+#
+# See Note [Stage number in build variables] in mk/config.mk.in.
+SRC_HC_OPTS_STAGE1 += $(WERROR)
+SRC_HC_OPTS_STAGE2 += $(WERROR)
 
-#####################
-# Warnings
 
 ifneq "$(GccIsClang)" "YES"
 
@@ -25,10 +32,6 @@ SRC_CC_WARNING_OPTS += -Wno-unknown-pragmas
 
 endif
 
-GhcStage1HcOpts += -fwarn-tabs
-GhcStage2HcOpts += -fwarn-tabs
-
-utils/hpc_dist-install_EXTRA_HC_OPTS += -fwarn-tabs
 
 
 ######################################################################
@@ -113,3 +116,26 @@ GhcBootLibExtraHcOpts += -fno-warn-deprecated-flags
 #
 GhcLibExtraHcOpts += -fno-warn-tabs
 GhcBootLibExtraHcOpts += -fno-warn-tabs
+
+
+# Note [Order of warning flags]
+#
+# In distdir-way-opts, build flags are added in the following order (this
+# list is not exhaustive):
+#
+#   * SRC_HC_OPTS(_STAGE$4)
+#   * ghc-options from .cabal files ($1_$2_HC_OPTS)
+#   * SRC_HC_WARNING_OPTS(_STAGE$4)
+#
+# Considerations:
+#
+#   * Most .cabal files specify -Wall. But not all, and not all building we
+#   do relies on .cabal files. So we have to add -Wall ourselves somewhere.
+#
+#   * Some .cabal also specify warning supression flags. Because -Wall
+#   overrides any warning supression flags that come before it, we have to
+#   make sure -Wall comes before any warning supression flags. So we add it
+#   to SRC_HC_OPTS.
+#
+#   * Similarly, our own warning supression should come after the -Wall from
+#   the .cabal files, so we do *not* add them to SRC_HC_OPTS.
diff --git a/rules/distdir-way-opts.mk b/rules/distdir-way-opts.mk
index 47f6f90237..92dbf346ff 100644
--- a/rules/distdir-way-opts.mk
+++ b/rules/distdir-way-opts.mk
@@ -19,7 +19,9 @@ define distdir-way-opts # args: $1 = dir, $2 = distdir, $3 = way, $4 = stage
 #   $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")
+#   $4 is the stage ("0", "1", "2") that the options are passed to
+#                                   See Note [Stage number in build variables]
+#                                   in mk/config.mk.in.
 # 
 # -----------------------------
 # The variables affecting Haskell compilations are as follows, including
@@ -40,10 +42,22 @@ define distdir-way-opts # args: $1 = dir, $2 = distdir, $3 = way, $4 = stage
 #  SRC_HC_OPTS           source-tree-wide GHC options      mk/config.mk.in
 #                                                          mk/build.mk
 #                                                          mk/validate.mk
-#   
+#                                                          mk/warnings.mk
+#
+#  SRC_HC_OPTS_STAGE$4   source-tree-wide GHC options,     mk/config.mk.in
+#                        supplied to the stage $4          mk/build.mk
+#                        compiler only                     mk/validate.mk
+#                                                          mk/warnings.mk
+#
 #  SRC_HC_WARNING_OPTS   source-tree-wide GHC warning      mk/config.mk.in
 #                        options                           mk/build.mk
 #                                                          mk/validate.mk
+#                                                          mk/warnings.mk
+#
+#  SRC_HC_WARNING_OPTS_STAGE$4                             mk/config.mk.in
+#                        source-tree-wide GHC warning      mk/build.mk
+#                        options, supplied to the          mk/validate.mk
+#                        stage $4 compiler only            mk/warnings.mk
 #   
 #  EXTRA_HC_OPTS         for supplying extra options on    make EXTRA_HC_OPTS=...
 #                        the command line   
@@ -60,6 +74,7 @@ define distdir-way-opts # args: $1 = dir, $2 = distdir, $3 = way, $4 = stage
 #  $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
+#                                                          mk/warnings.mk
 #   
 #  $1_$2_HC_PKGCONF      -package-db flag if necessary   rules/package-config.mk
 #   
@@ -100,6 +115,7 @@ $1_$2_$3_MOST_HC_OPTS = \
  $$(WAY_$3_HC_OPTS) \
  $$(CONF_HC_OPTS) \
  $$(SRC_HC_OPTS) \
+ $$(SRC_HC_OPTS_STAGE$4) \
  $$($1_HC_OPTS) \
  $$($1_$2_HC_PKGCONF) \
  $$(if $$($1_$2_PROG),, \
@@ -121,6 +137,7 @@ $1_$2_$3_MOST_HC_OPTS = \
  $$($1_$2_$3_HC_OPTS) \
  $$($$(basename $$(subst ./,,$$<))_HC_OPTS) \
  $$(SRC_HC_WARNING_OPTS) \
+ $$(SRC_HC_WARNING_OPTS_STAGE$4) \
  $$(EXTRA_HC_OPTS)
 
 $1_$2_$3_MOST_DIR_HC_OPTS = \
diff --git a/utils/mkUserGuidePart/Main.hs b/utils/mkUserGuidePart/Main.hs
index dd72c270d5..11283c0b95 100644
--- a/utils/mkUserGuidePart/Main.hs
+++ b/utils/mkUserGuidePart/Main.hs
@@ -76,11 +76,6 @@ flagsTable theFlags =
 inlineCode :: String -> ReST
 inlineCode s = "``" ++ s ++ "``"
 
--- | Generate a ReST substitution definition.
-substitution :: String -> ReST -> ReST
-substitution substName content =
-    unlines [".. |" ++ substName ++ "| ", content]
-
 heading :: Char -> String -> ReST
 heading chr title = unlines
     [ title