Add Note [How we configure the bundled windows toolchain]

hadrian/src/Rules/Generate.hs

@@ -444,7 +444,6 @@ generateGhcPlatformH = do
         , "#endif /* __GHCPLATFORM_H__ */"
         ]
 
--- See Note [tooldir: How GHC finds mingw on Windows]
 generateSettings :: Expr String
 generateSettings = do
     ctx <- getContext
@@ -533,6 +532,8 @@ generateSettings = do
 
     -- Like @'queryTarget'@ specialized to String, but replace occurrences of
     -- @topDirectory </> inplace/mingw@ with @$$tooldir/mingw@ in the resulting string
+    --
+    -- See Note [How we configure the bundled windows toolchain]
     queryTarget' :: (Toolchain.Target -> String) -> Expr String
     queryTarget' f = do
       topdir <- expr $ topDirectory

m4/fp_settings.m4

+dnl Note [How we configure the bundled windows toolchain]
+dnl ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+dnl As per Note [tooldir: How GHC finds mingw on Windows], when using the
+dnl bundled windows toolchain, the GHC settings file must refer to the
+dnl toolchain through a path relative to $$tooldir (binary distributions on
+dnl Windows should work without configure, so the paths must be relative to the
+dnl installation). However, hadrian expects the configured toolchain to use
+dnl full paths to the executable.
+dnl
+dnl This is how the bundled windows toolchain is configured, to define the
+dnl toolchain with paths to the executables, while still writing into GHC
+dnl settings the paths relative to $$tooldir:
+dnl
+dnl * If using the bundled toolchain, FP_SETUP_WINDOWS_TOOLCHAIN will be invoked
+dnl
+dnl * FP_SETUP_WINDOWS_TOOLCHAIN will set the toolchain variables to paths
+dnl   to the bundled toolchain (e.g. CFLAGS=/full/path/to/mingw/bin/gcc)
+dnl
+dnl * Later on, in FP_SETTINGS, we substitute occurrences of the path to the
+dnl   mingw tooldir by $$tooldir (see SUBST_TOOLDIR).
+dnl   The reason is the Settings* variants of toolchain variables are used by the bindist configure to
+dnl   create the settings file, which needs the windows bundled toolchain to be relative to $$tooldir.
+dnl
+dnl * Finally, hadrian will also substitute the mingw prefix by $$tooldir before writing the toolchain to the settings file (see generateSettings)
+dnl
+dnl The ghc-toolchain program isn't concerned with any of these complications:
+dnl it is passed either the full paths to the toolchain executables, or the bundled
+dnl mingw path is set first on $PATH before invoking it. And ghc-toolchain
+dnl will, as always, output target files with full paths to the executables.
+dnl
+dnl Hadrian accounts for this as it does for the toolchain executables
+dnl configured by configure -- in fact, hadrian doesn't need to know whether
+dnl the toolchain description file was generated by configure or by
+dnl ghc-toolchain.
+
 # SUBST_TOOLDIR
 # ----------------------------------
 # $1 - the variable where to search for occurrences of the path to the
 # distributed mingw, and update by substituting said occurrences by
 # the literal '$$tooldir/mingw'
+#
+# See Note [How we configure the bundled windows toolchain]
 AC_DEFUN([SUBST_TOOLDIR],
 [
-    dnl See Note [tooldir: How GHC finds mingw on Windows]
+    dnl and Note [How we configure the bundled windows toolchain]
     $1=`echo $$1 | sed 's%'"$mingwpath"'%$$tooldir/mingw%'`
 ])
 

m4/fp_setup_windows_toolchain.m4

@@ -65,7 +65,8 @@ AC_DEFUN([FP_SETUP_WINDOWS_TOOLCHAIN],[
         fi
     }
 
-    # See Note [tooldir: How GHC finds mingw on Windows]
+    # See Note [How we configure the bundled windows toolchain]
+    # and Note [tooldir: How GHC finds mingw on Windows]
     test -d inplace || mkdir inplace
 
     # NB. Download and extract the MingW-w64 distribution if required