Build system: cleanup utils/ghc-pkg/ghc.mk

There used to be a lot of custom make code to build ghc-pkg with the
stage0 compiler. Commit ac5a314504554ddef0e855ef9e2fcf51e961f4a6
thankfully cleaned this up, by using the build settings from the
ghc-pkg.cabal file.

This commit removes some remains of the old way of installing ghc-pkg
when Stage1Only=YES. Notably, we called both `build-prog` as
`shell-wrapper`. This is surely wrong, because `build-prog` already
calls `shell-wrapper`. It isn't needed to set WANT_INSTALLED_WRAPPER
either; build-prog does that for us.

This prevents the following warnings when Stage1Only=YES:
  utils/ghc-pkg/ghc.mk:46: warning:
    overriding commands for target `install_utils/ghc-pkg_dist_wrapper'
  utils/ghc-pkg/ghc.mk:37: warning:
    ignoring old commands for target `install_utils/ghc-pkg_dist_wrapper'

Also add more comments and restructure a bit.

Reviewed by: austin

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

1 files changed, 31 insertions, 17 deletions

diff --git a/utils/ghc-pkg/ghc.mk b/utils/ghc-pkg/ghc.mk
index 1bd44c9f12..c5f0b6254e 100644
--- a/utils/ghc-pkg/ghc.mk
+++ b/utils/ghc-pkg/ghc.mk
@@ -24,25 +24,38 @@ utils/ghc-pkg/dist-install/build/Version.hs: mk/project.mk | $$(dir $$@)/.
 
 utils/ghc-pkg_PACKAGE = ghc-pkg
 
+# Note [Why build certain utils twice?]
+#
+# We build certain utils twice: once with stage0, and once with stage1.
+# Examples are ghc-pkg and hsc2hs.
+#
+# These tools are needed during the bootstrapping process, so we have to use
+# stage0 to build them at first (stage1 doesn't exist yet). (side note: they're
+# also used later in the build process). We install them inplace.
+#
+# But we can't install these copies when you run 'make install'. The reason is
+# that when DYNAMIC_GHC_PROGRAMS=YES, we want to install copies that are
+# dynamically linked. But the stage0 copies are either statically linked, or
+# linked against libraries on the build machine.
+#
+# Therefore we build fresh copies, using the stage1 compiler, and install them
+# when you run 'make install'. They are not used for any other purpose.
+
 # -----------------------------------------------------------------------------
-# Cross-compile case: install our dist version
+# Build ghc-pkg with the stage0 compiler in the dist directory, and install
+# inplace. This is the copy we use during in-tree development.
+utils/ghc-pkg_dist_USES_CABAL = YES
+utils/ghc-pkg_dist_PROGNAME = ghc-pkg
+utils/ghc-pkg_dist_SHELL_WRAPPER = YES
+utils/ghc-pkg_dist_INSTALL_INPLACE = YES
 
 ifeq "$(Stage1Only)" "YES"
-
+# Install the copy of ghc-pkg from the dist directory when running 'make
+# install' (it's the only copy we have at this stage).
 utils/ghc-pkg_dist_INSTALL = YES
-utils/ghc-pkg_dist_SHELL_WRAPPER = YES
 utils/ghc-pkg_dist_INSTALL_SHELL_WRAPPER_NAME = ghc-pkg-$(ProjectVersion)
-utils/ghc-pkg_dist_WANT_INSTALLED_WRAPPER = YES
-
-$(eval $(call shell-wrapper,utils/ghc-pkg,dist))
-
 endif
 
-utils/ghc-pkg_dist_USES_CABAL = YES
-utils/ghc-pkg_dist_PROGNAME = ghc-pkg
-utils/ghc-pkg_dist_SHELL_WRAPPER = YES
-utils/ghc-pkg_dist_INSTALL_INPLACE = YES
-
 $(eval $(call build-prog,utils/ghc-pkg,dist,0))
 
 $(ghc-pkg_INPLACE) : | $(INPLACE_PACKAGE_CONF)/.
@@ -51,23 +64,24 @@ utils/ghc-pkg/dist/package-data.mk: \
     utils/ghc-pkg/dist/build/Version.hs
 
 # -----------------------------------------------------------------------------
-# Normal case: Build ghc-pkg with stage 1 and install it
+# Build another copy of ghc-pkg with the stage1 compiler in the dist-install
+# directory. Don't install it inplace (we use the dist copy there), but do
+# install it when running 'make install'.
+#
+# See Note [Why build certain utils twice?].
 
 ifneq "$(Stage1Only)" "YES"
-
 utils/ghc-pkg_dist-install_USES_CABAL = YES
-
 utils/ghc-pkg_dist-install_PROGNAME = ghc-pkg
 utils/ghc-pkg_dist-install_SHELL_WRAPPER = YES
+utils/ghc-pkg_dist-install_INSTALL_INPLACE = NO
 utils/ghc-pkg_dist-install_INSTALL = YES
 utils/ghc-pkg_dist-install_INSTALL_SHELL_WRAPPER_NAME = ghc-pkg-$(ProjectVersion)
-utils/ghc-pkg_dist-install_INSTALL_INPLACE = NO
 
 $(eval $(call build-prog,utils/ghc-pkg,dist-install,1))
 
 utils/ghc-pkg/dist-install/package-data.mk: \
     utils/ghc-pkg/dist-install/build/Version.hs
-
 endif
 
 # -----------------------------------------------------------------------------