Add pre and post build hooks

Run a program (named "preBuildHook") before doing a package build and
another program (named "postBuildHook") after the package is built.

These programs are project local and need to be in the `cabalHooks`
directory which is in the same directory as the `cabal.project` file.

Co-authored: Moritz Angermann <[email protected]>

cabal-install/src/Distribution/Client/ProjectBuilding/UnpackedPackage.hs

@@ -30,6 +30,7 @@ module Distribution.Client.ProjectBuilding.UnpackedPackage
 import Distribution.Client.Compat.Prelude
 import Prelude ()
 
+import Distribution.Client.Config
 import Distribution.Client.PackageHash (renderPackageHashInputs)
 import Distribution.Client.ProjectBuilding.Types
 import Distribution.Client.ProjectConfig
@@ -100,8 +101,8 @@ import qualified Data.ByteString.Lazy.Char8 as LBS.Char8
 import qualified Data.List.NonEmpty as NE
 
 import Control.Exception (ErrorCall, Handler (..), SomeAsyncException, assert, catches)
-import System.Directory (canonicalizePath, createDirectoryIfMissing, doesDirectoryExist, doesFileExist, removeFile)
-import System.FilePath (dropDrive, normalise, takeDirectory, (<.>), (</>))
+import System.Directory (canonicalizePath, createDirectoryIfMissing, doesDirectoryExist, doesFileExist, getCurrentDirectory, removeFile)
+import System.FilePath (dropDrive, dropFileName, normalise, takeDirectory, (<.>), (</>))
 import System.IO (Handle, IOMode (AppendMode), withFile)
 import System.Semaphore (SemaphoreName (..))
 
@@ -678,7 +679,32 @@ buildAndInstallUnpackedPackage
           runConfigure
         PBBuildPhase{runBuild} -> do
           noticeProgress ProgressBuilding
-          runBuild
+          hooksDir <- (</> "cabalHooks") <$> getCurrentDirectory
+          -- run preBuildHook. If it returns with 0, we assume the build was
+          -- successful. If not, run the build.
+          code <-
+            rawSystemExitCode
+              verbosity
+              (Just srcdir)
+              (hooksDir </> "preBuildHook")
+              [ (unUnitId $ installedUnitId rpkg)
+              , (getSymbolicPath srcdir)
+              , (getSymbolicPath builddir)
+              ]
+              `catchIO` (\_ -> return (ExitFailure 10))
+          when (code /= ExitSuccess) $ do
+            runBuild
+          -- not sure, if we want to care about a failed postBuildHook?
+          void $
+            rawSystemExitCode
+              verbosity
+              (Just srcdir)
+              (hooksDir </> "postBuildHook")
+              [ (unUnitId $ installedUnitId rpkg)
+              , (getSymbolicPath srcdir)
+              , (getSymbolicPath builddir)
+              ]
+              `catchIO` (\_ -> return (ExitFailure 10))
         PBHaddockPhase{runHaddock} -> do
           noticeProgress ProgressHaddock
           runHaddock

changelog.d/pr-9899

@@ -0,0 +1,14 @@
+synopsis: Add pre and post build hooks
+packages: cabal-install
+prs: #9899
+issues: #9892
+significance: significant
+
+description: {
+
+- Run a program (named "preBuildHook") before doing a package build and another program
+  (named "postBuildHook") after the package is built.
+- These programs are project local and need to be in the `cabalHooks` directory which is
+  in the same directory as the `cabal.project` file.
+- The absence of these programs will be ignored.
+}

doc/build-hooks.rst

@@ -0,0 +1,43 @@
+Build Hooks
+===========
+
+Build hooks are programs that are run before (pre-build hook) and
+after (post-build hook) a package (including package dependencies)
+is built. The hooks are completely generic and can even be absent
+(their absence is ignored).
+
+Build hooks are project local rather than global to the user
+because a single user may want to use one set of hooks in one
+project and another set of hoos (or even none at all) for another
+project.
+
+
+Possible Use Cases
+------------------
+
+Possible use cases include:
+
+* Fine grained benchmarking of individual package build times.
+* Build product caching.
+
+
+Location of Hook Files
+----------------------
+
+The two hook files are `cabalHooks/preBuildHook` and
+`cabalHooks/postBuildHook` where the `cabalHooks` directory is in
+the same directory as the `cabal.project` file. On UNIX style
+systems, these hooks need to be marked as user executable programs.
+
+
+Security Considerations
+-----------------------
+
+These build hooks are generic executable programs. They can potentially
+be malicious. For example, one might clone a Haskell project from
+say Github, that includes malicious build hooks so that when the user runs
+`cabal build all` these hooks will be run as the user. The most obvious
+malicious behaviour would be to delete all the user's files.
+
+For this reason, it is highly advisable to check for the existence
+of and the contents of any build hook files.

doc/index.rst

@@ -18,6 +18,7 @@ Welcome to the Cabal User Guide
    how-to-run-in-windows
    how-to-use-backpack
    how-to-report-bugs
+   build-hooks
 
 .. toctree::
    :caption: Cabal Reference