Build system: cleanup BUILD_DIRS + add lots of Notes

Summary:
See Note [CrossCompiling vs Stage1Only] in mk/config.mk.in.
See Note [Stage1Only vs stage=1] in mk/config.mk.in.
See Note [No stage2 packages when CrossCompiling or Stage1Only].

Also:
  * use stage2 to build mkUserGuidePart, as was probably intended.
    Now the following represent the same set of packages:
    - packages that we build with ghc-stage2
    - packages that depend on the ghc library
    Those packages are: haddock, mkUserGuidePart and ghctags.
  * don't let utils that don't depend on the ghc library depend on its
    package-data.mk file. Instead, let those utils directly depend on
    the package-data.mk files of the stage1 packages. Not sure if it
    improves anything, but I found it easier to explain what's going on
    this way.

(partially) reviewed by: austin

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

1 files changed, 53 insertions, 1 deletions

diff --git a/mk/config.mk.in b/mk/config.mk.in
index 9caa2b1daa..1b46ed73f7 100644
--- a/mk/config.mk.in
+++ b/mk/config.mk.in
@@ -504,17 +504,69 @@ LD_STAGE2       = $(LD)
 LD_STAGE3       = $(LD)
 
 # Cross-compiling options
-#
+# See Note [CrossCompiling vs Stage1Only]
 CrossCompiling        = @CrossCompiling@
 
 # Change this to YES if you're building a cross-compiler and don't
 # want to build stage 2.
+# See Note [CrossCompiling vs Stage1Only]
+# See Note [Stage1Only vs stage=1]
 Stage1Only = NO
 
 # Install stage 2 by default, or stage 1 in the cross compiler
 # case. Can be changed to 3
 INSTALL_GHC_STAGE= $(if $(filter YES,$(Stage1Only)),1,2)
 
+# Note [CrossCompiling vs Stage1Only]
+#
+# There are 4 possible settings:
+#
+# 1 CrossCompiling=NO Stage1Only=NO
+#   The default.
+#
+# 2 CrossCompiling=NO Stage1Only=YES
+#   Don't build ghc-stage2. See Note [Stage1Only vs stage=1].
+#
+# 3 CrossCompiling=YES Stage1Only=YES
+#   Building a cross-compiler (ghc-stage1). See [1] and
+#   Note [Stage1Only vs stage=1].
+#
+# 4 CrossCompiling=YES Stage1Only=NO
+#   Cross-compiling GHC itself. See [1].
+#
+# [1] https://ghc.haskell.org/trac/ghc/wiki/Building/CrossCompiling
+
+# Note [Stage1Only vs stage=1]
+#
+# Stage1Only=YES means:
+#   - don't build ghc-stage2 (the executable)
+#   - don't build utils that rely on ghc-stage2
+#     See Note [No stage2 packages when CrossCompiling or Stage1Only] in
+#     ./ghc.mk.
+#   - install ghc-stage1 instead of ghc-stage2
+#   - install the ghc-pkg that was built with the stage0 compiler
+#   - (*do* still build compiler/stage2 (i.e. the ghc library))
+#   - (*do* still build all other libraries)
+#
+# stage=1 means:
+#   - don't build compiler/stage2 (i.e. the ghc library)
+#   - don't build ghc-stage2 (the executable)
+#   Note: these are the only two things it does. If you want to exclude more
+#   stuff, combine it with Stage1Only=YES, or run make in the ghc or compiler
+#   directory.
+#
+# running make in the ghc or compiler directory means:
+#   - don't build any packages in the libraries/ directory, except the ones
+#     listed in PACKAGES_STAGE0 (i.e. the boot libraries)
+#
+# You may wonder why Stage1Only=YES still builds compiler/stage2. Quoting
+# simonmar in #7639:
+#
+#     "strictly speaking building compiler/stage2 is correct, because it is
+#     the ghc package that can be used with [ghc-stage1]. If you don't
+#     want to build it, then setting stage=1 in your mk/build.mk should
+#     disable it."
+
 # C compiler and linker flags from configure (e.g. -m<blah> to select
 # correct C compiler backend). The stage number is the stage of GHC
 # that is being used to compile with.