From dd74e9216948863a287fa93662298e39b653651f Mon Sep 17 00:00:00 2001
From: sheaf <sam.derbyshire@gmail.com>
Date: Tue, 30 Apr 2024 12:20:36 +0200
Subject: [PATCH] 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
---
 Cabal/src/Distribution/Simple/Build.hs | 62 +++++++++++++++++++++++++-
 changelog.d/pr-9950                    | 21 +++++++++
 2 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 changelog.d/pr-9950

diff --git a/Cabal/src/Distribution/Simple/Build.hs b/Cabal/src/Distribution/Simple/Build.hs
index a198f3d2f4f..d0999122645 100644
--- a/Cabal/src/Distribution/Simple/Build.hs
+++ b/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
 
diff --git a/changelog.d/pr-9950 b/changelog.d/pr-9950
new file mode 100644
index 00000000000..a961c953639
--- /dev/null
+++ b/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.
+}