Introduce SetupHooks

This commit introduces a new build-type, Hooks. A package using this
build type should provide a SetupHooks.hs module which exports
a value `setupHooks :: SetupHooks`. This is intended to replace the
Custom setup type. This allows Cabal to have finer-grained information
about the build, instead of having an opaque Setup executable to invoke.

Author: sheaf

Cabal-described/src/Distribution/Described.hs

@@ -355,7 +355,7 @@ instance Described BenchmarkType where
     describe _ = "exitcode-stdio-1.0"
 
 instance Described BuildType where
-    describe _ = REUnion ["Simple","Configure","Custom","Make","Default"]
+    describe _ = REUnion ["Simple","Configure","Custom","Hooks","Make","Default"]
 
 instance Described CompilerFlavor where
     describe _ = REUnion

Cabal-hooks/Cabal-hooks.cabal

@@ -0,0 +1,69 @@
+cabal-version: 2.2
+name:          Cabal-hooks
+version:       0.1
+copyright:     2023, Cabal Development Team
+license:       BSD-3-Clause
+license-file:  LICENSE
+author:        Cabal Development Team <cabal-devel@haskell.org>
+maintainer:    cabal-devel@haskell.org
+homepage:      http://www.haskell.org/cabal/
+bug-reports:   https://github.com/haskell/cabal/issues
+synopsis:      API for the Hooks build-type
+description:
+  User-facing API for the Hooks build-type.
+category:       Distribution
+build-type:     Simple
+
+extra-source-files:
+  readme.md changelog.md
+
+source-repository head
+  type:     git
+  location: https://github.com/haskell/cabal/
+  subdir:   Cabal-hooks
+
+library
+  default-language: Haskell2010
+  hs-source-dirs: src
+
+  build-depends:
+    Cabal-syntax    >= 3.11      && < 3.13,
+    Cabal           >= 3.11      && < 3.13,
+    base            >= 4.9       && < 5,
+    containers      >= 0.5.0.0   && < 0.8,
+    filepath        >= 1.3.0.1   && < 1.5,
+    transformers    >= 0.5.6.0   && < 0.7
+
+  ghc-options: -Wall -fno-ignore-asserts -fwarn-tabs -fwarn-incomplete-uni-patterns -fwarn-incomplete-record-updates
+
+  exposed-modules:
+    Distribution.Simple.SetupHooks
+
+  other-extensions:
+    BangPatterns
+    CPP
+    DefaultSignatures
+    DeriveDataTypeable
+    DeriveFoldable
+    DeriveFunctor
+    DeriveGeneric
+    DeriveTraversable
+    ExistentialQuantification
+    FlexibleContexts
+    FlexibleInstances
+    GeneralizedNewtypeDeriving
+    ImplicitParams
+    KindSignatures
+    LambdaCase
+    NondecreasingIndentation
+    OverloadedStrings
+    PatternSynonyms
+    RankNTypes
+    RecordWildCards
+    ScopedTypeVariables
+    StandaloneDeriving
+    Trustworthy
+    TypeFamilies
+    TypeOperators
+    TypeSynonymInstances
+    UndecidableInstances

Cabal-hooks/LICENSE

@@ -0,0 +1,34 @@
+Copyright (c) 2003-2023, Cabal Development Team.
+See the AUTHORS file for the full list of copyright holders.
+
+See */LICENSE for the copyright holders of the subcomponents.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+    * Neither the name of Isaac Jones nor the names of other
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Cabal-hooks/changelog.md

@@ -0,0 +1,6 @@
+# Changelog for `Cabal-hooks`
+
+## 0.1 – December 2023
+
+  * Initial release of the `Hooks` API.
+

Cabal-hooks/readme.md

@@ -0,0 +1,62 @@
+# `Cabal-hooks`
+
+This library provides an API for the `Cabal` `Hooks` build type.
+
+## What is the `Hooks` build type?
+
+The `Hooks` build type is a new `Cabal` build type that is scheduled to
+replace the `Custom` build type, providing better integration with
+the rest of the Haskell ecosystem.
+
+The original specification for the `Hooks` build type can be found in
+the associated [Haskell Foundation Tech Proposal](https://github.com/haskellfoundation/tech-proposals/pull/60).
+
+These *setup hooks* allow package authors to customise the configuration and
+building of a package by providing certain hooks that get folded into the
+general package configuration and building logic within `Cabal`.
+
+## Defining a package with custom hooks
+
+To use the `Hooks` build type, you will need to
+
+  * Update your `.cabal` file by:
+
+      - declaring `build-type: Hooks`,
+      - declaring a `custom-setup` stanza, with a `setup-depends`
+        field which includes a dependency on `Cabal-hooks`.
+  
+  * Define a Haskell module `SetupHooks`, which must be placed
+    at the root of your project and must define a value
+    `setupHooks :: SetupHooks`.
+
+That is, your `.cabal` file should contain the following
+
+```cabal
+-- my-package.cabal
+name: my-package
+build-type: Hooks
+
+custom-setup
+  setup-depends:
+    Cabal-hooks >= 0.1 && < 0.2
+```
+
+and your `SetupHooks.hs` file should look like:
+
+```haskell
+-- SetupHooks.hs
+module SetupHooks ( setupHooks ) where
+
+-- Cabal-hooks
+import Distribution.Simple.SetupHooks
+
+setupHooks :: SetupHooks
+setupHooks = ...
+  -- use the API provided by 'Distribution.Simple.SetupHooks'
+  -- to define the hooks relevant to your package
+```
+
+## Using the API
+
+The [Haddock documentation](https://hackage.haskell.org/package/Cabal-hooks)
+should help you get started using this library's API.

Cabal-hooks/src/Distribution/Simple/SetupHooks.hs

@@ -17,7 +17,8 @@ This module defines the interface for the @Hooks@ @build-type@.
 
 To write a package that implements @build-type: Hooks@, you should define
 a module @SetupHooks.hs@ which exports a value @setupHooks :: 'SetupHooks'@.
-This is a record that declares actions to hook into the cabal build process.
+This is a record that declares actions that should be hooked into the
+cabal build process.
 
 See 'SetupHooks' for more details.
 -}
@@ -97,9 +98,7 @@ module Distribution.Simple.SetupHooks
 
   -- **** File/directory monitoring
   , addRuleMonitors
-  , MonitorFilePath(..)
-  , MonitorKindFile(..)
-  , MonitorKindDir(..)
+  , module Distribution.Simple.FileMonitor.Types
 
     -- * Install hooks
   , InstallHooks(..), noInstallHooks
@@ -120,17 +119,27 @@ module Distribution.Simple.SetupHooks
     -- | These are functions provided as part of the @Hooks@ API.
     -- It is recommended to import them from this module as opposed to
     -- manually importing them from inside the Cabal module hierarchy.
-  , installFileGlob, addKnownPrograms
+
+    -- *** Copy/install functions
+  , installFileGlob
+
+    -- *** Interacting with the program database
+  , Program(..), ConfiguredProgram(..), ProgArg
+  , ProgramLocation(..)
+  , ProgramDb
+  , addKnownPrograms
+  , configureUnconfiguredProgram
+  , simpleProgram
 
     -- ** General @Cabal@ datatypes
   , Verbosity, Compiler(..), Platform(..), Suffix(..)
 
     -- *** Package information
   , LocalBuildConfig, LocalBuildInfo, PackageBuildDescr
-      -- SetupHooks TODO: we can't simply re-export all the fields of
-      -- LocalBuildConfig etc, due to the presence of duplicate record fields.
-      -- Ideally we'd like to e.g. re-export LocalBuildConfig
-      -- qualified, but qualified re-exports aren't a thing currently.
+      -- NB: we can't simply re-export all the fields of LocalBuildConfig etc,
+      -- due to the presence of duplicate record fields.
+      -- Ideally, we'd like to e.g. re-export LocalBuildConfig qualified,
+      -- but qualified re-exports aren't a thing currently.
 
   , PackageDescription(..)
 
@@ -146,9 +155,6 @@ module Distribution.Simple.SetupHooks
   , emptyLibrary, emptyForeignLib, emptyExecutable
   , emptyTestSuite, emptyBenchmark
 
-    -- ** Programs
-  , Program, ConfiguredProgram, ProgramDb, ProgArg
-
   )
 where
 import Distribution.PackageDescription
@@ -166,16 +172,24 @@ import Distribution.Simple.Compiler
   ( Compiler(..) )
 import Distribution.Simple.Errors
   ( CabalException(SetupHooksException) )
+import Distribution.Simple.FileMonitor.Types
 import Distribution.Simple.Install
   ( installFileGlob )
 import Distribution.Simple.LocalBuildInfo
   ( componentBuildDir )
 import Distribution.Simple.PreProcess.Types
   ( Suffix(..) )
 import Distribution.Simple.Program.Db
-  ( ProgramDb, addKnownPrograms )
+  ( ProgramDb, addKnownPrograms
+  , configureUnconfiguredProgram
+  )
+import Distribution.Simple.Program.Find
+  ( simpleProgram )
 import Distribution.Simple.Program.Types
-  ( Program, ConfiguredProgram, ProgArg )
+  ( Program(..), ConfiguredProgram(..)
+  , ProgArg
+  , ProgramLocation(..)
+  )
 import Distribution.Simple.Setup
   ( BuildFlags(..)
   , ConfigFlags(..)
@@ -250,7 +264,9 @@ Usage example:
 > custom-setup
 >   setup-depends:
 >     base        >= 4.18 && < 5,
->     Cabal-hooks >= 0.1  && < 0.3
+>     Cabal-hooks >= 0.1  && < 0.2
+>
+> The declared Cabal version should also be at least 3.12.
 
 > -- In SetupHooks.hs, next to your .cabal file
 > module SetupHooks where
@@ -304,34 +320,39 @@ For example, to generate modules inside a given component, you should:
 -}
 
 {- $preBuildRules
-Pre-build hooks are specified in the form of a collection of pre-build 'Rules'.
+Pre-build hooks are specified as a collection of pre-build 'Rules'.
+Each t'Rule' consists of:
 
-Pre-build rules are specified as a collection of rules. Each t'Rule' declares
-its dependencies, its outputs, and refers to a command to run in order to
-execute the rule in the form of a t'RuleCommands'.
+  - a specification of its static dependencies and outputs,
+  - the commands that execute the rule.
+
+Rules are constructed using either one of the 'staticRule' or 'dynamicRule'
+smart constructors. Directly constructing a t'Rule' using the constructors of
+that data type is not advised, as this relies on internal implementation details
+which are subject to change in between versions of the `Cabal-hooks` library.
 
 Note that:
 
-  - file dependencies are not specified directly by 'FilePath' but rather use
-    the 'Location' type,
-  - rules can directly depend on other rules, which requires the ability to
-    refer to a rule by 'RuleId',
-  - rules refer to the actions that execute them using static pointers, in order
-    to enable serialisation/deserialisation of rules,
-  - rules can additionally monitor files or directories, which determines
+  - To declare the dependency on the output of a rule, one must refer to the
+    rule directly, and not to the path to the output executing that rule will
+    eventually produce.
+    To do so, registering a t'Rule' with the API returns a unique identifier
+    for that rule, in the form of a t'RuleId'.
+  - File dependencies and outputs are not specified directly by
+    'FilePath', but rather use the 'Location' type (which is more convenient
+    when working with preprocessors).
+  - Rules refer to the actions that execute them using static pointers, in order
+    to enable serialisation/deserialisation of rules.
+  - Rules can additionally monitor files or directories, which determines
     when to re-compute the entire set of rules.
-
-To construct a t'Rule', you should use one of the 'staticRule' or 'dynamicRule'
-smart constructors, to avoid relying on internal implementation details of
-the t'Rule' datatype.
 -}
 
 {- $rulesDemand
 Rules can declare various kinds of dependencies:
 
   - 'staticDependencies': files or other rules that a rule statically depends on,
   - extra dynamic dependencies, using the 'DynamicRuleCommands' constructor,
-  - 'MonitoredFileOrDir': additional files or directories to monitor.
+  - 'MonitorFilePath': additional files and directories to monitor.
 
 Rules are considered __out-of-date__ precisely when any of the following
 conditions apply:
@@ -377,11 +398,11 @@ Defining pre-build rules can be done in the following style:
 >       let cmd1 = mkCommand (static Dict) $ static \ arg -> do { .. }
 >           cmd2 = mkCommand (static Dict) $ static \ arg -> do { .. }
 >       myData <- liftIO someIOAction
->       addRuleMonitors [ MonitorDir "someSearchDir" DirContents ]
->       registerRule_ $ staticRule (cmd1 arg1) deps1 outs1
->       registerRule_ $ staticRule (cmd1 arg2) deps2 outs2
->       registerRule_ $ staticRule (cmd1 arg3) deps3 outs3
->       registerRule_ $ staticRule (cmd2 arg4) deps4 outs4
+>       addRuleMonitors [ monitorDirectory "someSearchDir" ]
+>       registerRule_ "rule_1_1" $ staticRule (cmd1 arg1) deps1 outs1
+>       registerRule_ "rule_1_2" $ staticRule (cmd1 arg2) deps2 outs2
+>       registerRule_ "rule_1_3" $ staticRule (cmd1 arg3) deps3 outs3
+>       registerRule_ "rule_2_4" $ staticRule (cmd2 arg4) deps4 outs4
 
 Here we use the 'rules', 'staticRule' and 'mkCommand' smart constructors,
 rather than directly using the v'Rules', v'Rule' and v'Command' constructors,
@@ -456,5 +477,5 @@ findFileInDirs file dirs =
       | path <- nub dirs
       ]
 
-  -- SetupHooks TODO: add API functions that do searching and declare
-  -- the appropriate monitoring at the same time.
+  -- TODO: add API functions that search and declare the appropriate monitoring
+  -- at the same time.

Cabal-syntax/src/Distribution/PackageDescription/Parsec.hs

@@ -761,6 +761,10 @@ checkForUndefinedCustomSetup gpd = do
       parseFailure zeroPos $
         "Since cabal-version: 1.24 specifying custom-setup section is mandatory"
 
+  when (buildType pd == Hooks && isNothing (setupBuildInfo pd)) $
+    parseFailure zeroPos $
+      "Packages with build-type: Hooks require a custom-setup stanza"
+
 -------------------------------------------------------------------------------
 -- Post processing of internal dependencies
 -------------------------------------------------------------------------------
@@ -988,7 +992,7 @@ parseHookedBuildInfo' lexWarnings fs = do
 -- RFC5234 ABNF):
 --
 -- @
--- newstyle-spec-version-decl = "cabal-version" *WS ":" *WS newstyle-pec-version *WS
+-- newstyle-spec-version-decl = "cabal-version" *WS ":" *WS newstyle-spec-version *WS
 --
 -- spec-version               = NUM "." NUM [ "." NUM ]
 --