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, 2 insertions, 0 deletions

diff --git a/ghc/ghc.mk b/ghc/ghc.mk
index 0ad059f7ff..f8c6b09e3f 100644
--- a/ghc/ghc.mk
+++ b/ghc/ghc.mk
@@ -100,6 +100,7 @@ echo 'executablename="$$exedir/ghc"' >> "$(WRAPPER)"
 endef
 
 # if stage is set to something other than "1" or "", disable stage 1
+# See Note [Stage1Only vs stage=1] in mk/config.mk.in.
 ifneq "$(filter-out 1,$(stage))" ""
 ghc_stage1_NOT_NEEDED = YES
 endif
@@ -108,6 +109,7 @@ ifneq "$(filter-out 2,$(stage))" ""
 ghc_stage2_NOT_NEEDED = YES
 endif
 # When cross-compiling, the stage 1 compiler is our release compiler, so omit stage 2
+# See Note [Stage1Only vs stage=1] in mk/config.mk.in.
 ifeq "$(Stage1Only)" "YES"
 ghc_stage2_NOT_NEEDED = YES
 endif