Make build system: Generalize and/or document distdirs

`manual-package-config` should not hard-code the distdir, and no
longer does

Elsewhere, we must continue to hard-code due to inconsitent distdir
names across stages, so we document this referring to the existing note
"inconsistent distdirs".

(cherry picked from commit 9bd6daa4af5893b9da97e75060248a8c2faf3b0b)

5 files changed, 26 insertions, 10 deletions

diff --git a/rts/ghc.mk b/rts/ghc.mk
index ef5fc7bbb4..efa4af5462 100644
--- a/rts/ghc.mk
+++ b/rts/ghc.mk
@@ -633,7 +633,7 @@ ifeq "$(HaveLibMingwEx)" "YES"
 rts_PACKAGE_CPP_OPTS += -DHAVE_LIBMINGWEX
 endif
 
-$(eval $(call manual-package-config,rts,1))
+$(eval $(call manual-package-config,rts,dist,1))
 
 rts/dist/package.conf.inplace : $(includes_1_H_CONFIG) $(includes_1_H_PLATFORM) $(includes_1_H_VERSION)
 
diff --git a/rules/build-package.mk b/rules/build-package.mk
index e8af273ad0..a7d32ac06b 100644
--- a/rules/build-package.mk
+++ b/rules/build-package.mk
@@ -154,6 +154,10 @@ $(call haddock,$1,$2)
 endif
 
 # Don't put bootstrapping packages in the bindist
+#
+# See Note [inconsistent distdirs] in rules/build-package-way.mk for why
+# we hard-code dist-install; GHC will use stage2/stage3 here so we
+# cannot use the distdir parameter.
 ifneq "$3" "0"
 BINDIST_EXTRAS += $1/*.cabal $$(wildcard $1/*.buildinfo) $$(wildcard $1/dist-install/build/*.buildinfo) $1/$2/setup-config $1/LICENSE
 BINDIST_EXTRAS += $$($1_$2_INSTALL_INCLUDES_SRCS)
diff --git a/rules/build-prog.mk b/rules/build-prog.mk
index 0528c15fc9..e94f310c48 100644
--- a/rules/build-prog.mk
+++ b/rules/build-prog.mk
@@ -196,6 +196,10 @@ ifneq "$$(BINDIST)" "YES"
 
 # The quadrupled $'s here are because the _<way>_LIB variables aren't
 # necessarily set when this part of the makefile is read
+#
+# See Note [inconsistent distdirs] in rules/build-package-way.mk for why
+# we are computing the dist-dir from the GHC stage and not just using
+# the distdir parameter.
 $1/$2/build/tmp/$$($1_$2_PROG) $1/$2/build/tmp/$$($1_$2_PROG).dll : \
     $$(foreach dep,$$($1_$2_TRANSITIVE_DEP_COMPONENT_IDS),\
         $$$$($$(dep)_dist-$(if $(filter 0,$3),boot,install)_PROGRAM_DEP_LIB))
@@ -319,6 +323,10 @@ $(call dependencies,$1,$2,$3)
 # so we need to add a dependency for that. As we don't know which
 # module contains Main, we just make all modules in the program
 # depend on it.
+#
+# See Note [inconsistent distdirs] in rules/build-package-way.mk for why
+# we hard-code dist-install; GHC will use stage2/stage3 here so we
+# cannot use the distdir parameter.
 ifneq "$3" "0"
 $$(foreach o,$$($1_$2_$$($1_$2_PROGRAM_WAY)_HS_OBJS),$$(eval $$(call add-dependency,$$o,libraries/base/dist-install/build/GHC/TopHandler.$$($$($1_$2_PROGRAM_WAY)_osuf))))
 endif
diff --git a/rules/haddock.mk b/rules/haddock.mk
index e624e4afb1..4f084f86e3 100644
--- a/rules/haddock.mk
+++ b/rules/haddock.mk
@@ -40,6 +40,9 @@ endif
 .PHONY: html_$1
 html_$1 : $$($$($1_PACKAGE)-$$($1_$2_VERSION)_HADDOCK_FILE)
 
+# See Note [inconsistent distdirs] in rules/build-package-way.mk for why
+# we hard-code dist-install; GHC will use stage2/stage3 here so we
+# cannot use the distdir parameter.
 $$($1_PACKAGE)-$$($1_$2_VERSION)_HADDOCK_DEPS = $$(foreach n,$$($1_$2_DEPS),$$($$n_HADDOCK_FILE) $$($$n_dist-install_$$(HADDOCK_WAY)_LIB))
 
 # We don't pass -dcore-lint to haddock because it caused a performance regression in #13789
diff --git a/rules/manual-package-config.mk b/rules/manual-package-config.mk
index 64d6f1aec6..0c43f6247d 100644
--- a/rules/manual-package-config.mk
+++ b/rules/manual-package-config.mk
@@ -14,16 +14,17 @@
 define manual-package-config
 # args:
 # $1 = dir
-# $2 = stage
-$(call trace, manual-package-config($1, $2))
-$(call profStart, manual-package-config($1, $2))
+# $2 = distdir
+# $3 = stage
+$(call trace, manual-package-config($1, $2, $3))
+$(call profStart, manual-package-config($1, $2, $3))
 
-$1/dist/package.conf.inplace : $1/package.conf.in $$$$(ghc-pkg_INPLACE) | $$$$(dir $$$$@)/.
+$1/$2/package.conf.inplace : $1/package.conf.in $$$$(ghc-pkg_INPLACE) | $$$$(dir $$$$@)/.
 	$$(HS_CPP) -P \
 		-DTOP='"$$(TOP)"' \
 		$$($1_PACKAGE_CPP_OPTS) \
 		$$(addprefix -I,$$(GHC_INCLUDE_DIRS)) \
-		-I$$(BUILD_$2_INCLUDE_DIR) \
+		-I$$(BUILD_$3_INCLUDE_DIR) \
 		-x c $$< -o $$@.raw
 	grep -v '^#pragma GCC' $$@.raw | \
 	    sed -e 's/""//g' -e 's/:[ 	]*,/: /g' > $$@
@@ -32,18 +33,18 @@ $1/dist/package.conf.inplace : $1/package.conf.in $$$$(ghc-pkg_INPLACE) | $$$$(d
 
 # This is actually a real file, but we need to recreate it on every
 # "make install", so we declare it as phony
-.PHONY: $1/dist/package.conf.install
-$1/dist/package.conf.install: | $$$$(dir $$$$@)/.
+.PHONY: $1/$2/package.conf.install
+$1/$2/package.conf.install: | $$$$(dir $$$$@)/.
 	$$(HS_CPP) -P \
 		-DINSTALLING \
 		-DLIB_DIR='"$$(if $$(filter YES,$$(RelocatableBuild)),$$$$topdir,$$(ghclibdir))"' \
 		-DINCLUDE_DIR='"$$(if $$(filter YES,$$(RelocatableBuild)),$$$$topdir,$$(ghclibdir))/include"' \
 		$$($1_PACKAGE_CPP_OPTS) \
 		$$(addprefix -I,$$(GHC_INCLUDE_DIRS)) \
-		-I$$(BUILD_$2_INCLUDE_DIR) \
+		-I$$(BUILD_$3_INCLUDE_DIR) \
 		-x c $1/package.conf.in -o $$@.raw
 	grep -v '^#pragma GCC' $$@.raw | \
 	    sed -e 's/""//g' -e 's/:[ 	]*,/: /g' >$$@
 
-$(call profEnd, manual-package-config($1, $2))
+$(call profEnd, manual-package-config($1, $2, $3))
 endef