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.

Tests include:

  - error when returning an invalid component diff in a
    per-component pre-configure hook
  - error when declaring pre-build rules whose dependency
    graph contains cycles
  - error when we cannot find a dependency of a pre-build rule
  - warning when there are pre-build rules that are declared but
    never demanded
  - correctness tests for SetupHooks, e.g. that
    pre-build rules are run in dependency order (see the
    `SetupHooksRuleOrdering` test)

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 <[email protected]>
+maintainer:    [email protected]
+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,64 @@
+# `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:
+
+      - using `cabal-version >= 3.14`,
+      - 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
+cabal-version: 3.14
+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.