# `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.