Reinstate 'initialBuildSteps' function

This patch reinstates the 'initialBuildSteps' function, as it is
used by stack in its implementation of the multi-repl feature.

A deprecation warning has been added to that function: calling it does
not suffice to prepare the sources for a package, as there are other
steps that one might also need to perform:

  - running pre-processors (such as alex/happy)
  - running pre-build hooks or custom logic (in build-type: Hooks
    or build-type: Custom or Configure)

Consumers wanting to prepare the sources of a package, e.g. in order to
launch a REPL session, are advised to run
`Setup repl --repl-multi-file=<fn>` instead.

Fixes #9856

Author: sheaf

Cabal/src/Distribution/Simple/Build.hs

@@ -39,6 +39,10 @@ module Distribution.Simple.Build
   , writeBuiltinAutogenFiles
   , writeAutogenFiles
 
+    -- ** Legacy functions
+  , componentInitialBuildSteps
+  , initialBuildSteps
+
     -- * Internal package database creation
   , createInternalPackageDB
   ) where
@@ -1029,6 +1033,61 @@ replFLib flags pkg_descr lbi exe clbi =
         GHC -> GHC.replFLib flags NoFlag pkg_descr lbi exe clbi
         _ -> dieWithException verbosity REPLNotSupported
 
+-- | Runs 'componentInitialBuildSteps' on every configured component.
+--
+-- Legacy function: does not run pre-build hooks or pre-processors. This function
+-- is insufficient on its own to prepare the build for a package.
+--
+-- Consumers wanting to prepare the sources of a package, e.g. in order to
+-- launch a REPL session, are advised to run @Setup repl --repl-multi-file=<fn>@
+-- instead.
+initialBuildSteps
+  :: FilePath
+  -- ^ "dist" prefix
+  -> PackageDescription
+  -- ^ mostly information from the .cabal file
+  -> LocalBuildInfo
+  -- ^ Configuration information
+  -> Verbosity
+  -- ^ The verbosity to use
+  -> IO ()
+initialBuildSteps distPref pkg_descr lbi verbosity =
+  withAllComponentsInBuildOrder pkg_descr lbi $ \_comp clbi ->
+    componentInitialBuildSteps distPref pkg_descr lbi clbi verbosity
+{-# DEPRECATED
+  initialBuildSteps
+  "This function does not prepare all source files for a package. Suggestion: use 'Setup repl --repl-multi-file=<fn>'."
+  #-}
+
+-- | Creates the autogenerated files for a particular configured component.
+--
+-- Legacy function: does not run pre-build hooks or pre-processors. This function
+-- is insufficient on its own to prepare the build for a component.
+--
+-- Consumers wanting to prepare the sources of a component, e.g. in order to
+-- launch a REPL session, are advised to run
+-- @Setup repl <compName> --repl-multi-file=<fn>@ instead.
+componentInitialBuildSteps
+  :: FilePath
+  -- ^ "dist" prefix
+  -> PackageDescription
+  -- ^ mostly information from the .cabal file
+  -> LocalBuildInfo
+  -- ^ Configuration information
+  -> ComponentLocalBuildInfo
+  -- ^ Build info about the component
+  -> Verbosity
+  -- ^ The verbosity to use
+  -> IO ()
+componentInitialBuildSteps _distPref pkg_descr lbi clbi verbosity = do
+  let compBuildDir = interpretSymbolicPathLBI lbi $ componentBuildDir lbi clbi
+  createDirectoryIfMissingVerbose verbosity True compBuildDir
+  writeBuiltinAutogenFiles verbosity pkg_descr lbi clbi
+{-# DEPRECATED
+  componentInitialBuildSteps
+  "This function does not prepare all source files for a component. Suggestion: use 'Setup repl <compName> --repl-multi-file=<fn>'."
+  #-}
+
 -- | Creates the autogenerated files for a particular configured component,
 -- and runs the pre-build hook.
 preBuildComponent
@@ -1042,7 +1101,8 @@ preBuildComponent
 preBuildComponent preBuildHook verbosity lbi tgt = do
   let pkg_descr = localPkgDescr lbi
       clbi = targetCLBI tgt
-  createDirectoryIfMissingVerbose verbosity True (interpretSymbolicPathLBI lbi $ componentBuildDir lbi clbi)
+      compBuildDir = interpretSymbolicPathLBI lbi $ componentBuildDir lbi clbi
+  createDirectoryIfMissingVerbose verbosity True compBuildDir
   writeBuiltinAutogenFiles verbosity pkg_descr lbi clbi
   preBuildHook lbi tgt
 

changelog.d/pr-9950

@@ -0,0 +1,21 @@
+synopsis: Re-instate `initialBuildSteps`
+packages: Cabal
+issues: #9856
+prs: #9950
+
+description: {
+
+The `initialBuildSteps` function from `Distribution.Simple.Build`, which had
+been hastily removed, has been reinstated.
+
+It now comes with a deprecation warning: calling that function does not suffice
+to prepare the sources for a package, as there are other steps that one might
+also need to perform:
+
+  - running pre-processors (such as alex/happy)
+  - running pre-build hooks or custom logic
+    (in build-type: Hooks or build-type: Custom or Configure)
+
+Consumers wanting to prepare the sources of a package, e.g. in order to launch a
+REPL session, are advised to run `setup repl --repl-multi-file=<fn>` instead.
+}