Merge pull request #9961 from haskell/mergify/bp/3.12/pr-9950

Reinstate 'initialBuildSteps' function (backport #9950)

Author: mergify[bot]

Cabal/src/Distribution/Simple/Build.hs

@@ -34,6 +34,10 @@ module Distribution.Simple.Build
   , writeBuiltinAutogenFiles
   , writeAutogenFiles
 
+    -- ** Legacy functions
+  , componentInitialBuildSteps
+  , initialBuildSteps
+
     -- * Internal package database creation
   , createInternalPackageDB
   ) where
@@ -928,6 +932,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 = 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>'."
+  #-}
+
 -- | Pre-build steps for a component: creates the autogenerated files
 -- for a particular configured component.
 preBuildComponent
@@ -939,7 +998,8 @@ preBuildComponent
 preBuildComponent verbosity lbi tgt = do
   let pkg_descr = localPkgDescr lbi
       clbi = targetCLBI tgt
-  createDirectoryIfMissingVerbose verbosity True (componentBuildDir lbi clbi)
+      compBuildDir = componentBuildDir lbi clbi
+  createDirectoryIfMissingVerbose verbosity True compBuildDir
   writeBuiltinAutogenFiles verbosity pkg_descr lbi clbi
 
 -- | Generate and write to disk all built-in autogenerated files

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.
+}