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 that should be hooked into the cabal build process.

See also the introductory how to guide in the Cabal user manual.

A Cabal package with Hooks build-type must define the Haskell module SetupHooks which defines a value setupHooks :: SetupHooks.

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.

This mechanism replaces the Custom build-type, providing better integration with the rest of the Haskell ecosystem.

Usage example:

-- In your .cabal file
build-type: Hooks

custom-setup
  setup-depends:
    base        >= 4.18 && < 5,
    Cabal-hooks >= 3.14 && < 3.15

The declared Cabal version should also be at least 3.14.

-- In SetupHooks.hs, next to your .cabal file
module SetupHooks where
import Distribution.Simple.SetupHooks ( SetupHooks, noSetupHooks )

setupHooks :: SetupHooks
setupHooks =
 noSetupHooks
   { configureHooks = myConfigureHooks
   , buildHooks = myBuildHooks }

Note that SetupHooks can be monoidally combined, e.g.:

module SetupHooks where
import Distribution.Simple.SetupHooks
import qualified SomeOtherLibrary ( setupHooks )

setupHooks :: SetupHooks
setupHooks = SomeOtherLibrary.setupHooks <> mySetupHooks

mySetupHooks :: SetupHooks
mySetupHooks = ...

SetupHooks allow hooks into the following phases:

• The configure phase, via ConfigureHooks.

  There are three hooks into the configure phase:

  • Package-wide pre-configure hook.

    This hook enables custom logic in the style of traditional ./configure scripts, e.g. finding out information about the system and configuring dependencies.

  • Package-wide post-configure hook.

    This hook is mostly used to write write custom package-wide information to disk so that the next step can read it without repeating work.

  • Per-component pre-configure hooks.

    These hooks are used to modify individual components, e.g. declaring new modules (such as autogenerated modules whose module names are not statically known) or specifying per-component flags to be used when building each component.

    You can think of this step as dynamically updating the stanza for a single component in the .cabal file of a package.

• The build phase, via BuildHooks.

  There are two hooks into the build phase:

  • Per-component pre-build rules.

    A rule can be thought of an invocation of a code generator; each rule specifies how to build a particular output.

    You can have rules that don't depend on any inputs (e.g. directly generate a collection of modules programmatically, perhaps from some kind of parsed schema), as well as preprocessor-like rules that take in input files, e.g. the Happy parser generator that takes in a .y file and generates a corresponding .hs file.

    This rather elaborate setup (compared to a one-shot program that generates the required modules) allows proper recompilation checking. See also https://well-typed.com/blog/2025/01/cabal-hooks/#pre-build-rules for some worked examples of pre-build rules.

  • Per-component post-build hooks.

    These can be thought of as "pre-linking hooks" and allow injecting additional data into the final executable.

• The install phase, via InstallHooks.

  There is a single, per-component install hook. This allows copying over additional files when installing a component (library/executable).

Configure hooks can be used to augment the Cabal configure logic with package-specific logic. The main principle is that the configure hooks can feed into updating the PackageDescription of a cabal package. From then on, this package configuration is set in stone, and later hooks (e.g. hooks into the build phase) can no longer modify this configuration; instead they will receive this configuration in their inputs, and must honour it.

Configuration happens at two levels:

• global configuration covers the entire package,
• local configuration covers a single component.

Once the global package configuration is done, all hooks work on a per-component level. The configuration hooks thus follow a simple philosophy:

• All modifications to global package options must use preConfPackageHook.
• All modifications to component configuration options must use preConfComponentHook.

For example, to generate modules inside a given component, you should:

• In the per-component configure hook, declare the modules you are going to generate by adding them to the autogenModules field for that component (unless you know them ahead of time, in which case they can be listed textually in the .cabal file of the project).
• In the build hooks, describe the actions that will generate these modules.

Pre-build hooks are specified as a collection of pre-build Rules. Each Rule consists of:

• a specification of its static dependencies and outputs,
• the commands that execute the rule.

You can think of a Rule as describing a particular invocation of a code generator or preprocessor, with the Command specifying the particular command that will be executed.

Rules are constructed using either one of the staticRule or dynamicRule smart constructors. Directly constructing a 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:

• 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.

  This is achieved by using the RuleId returned by registerRule, which is the unique identifier for that rule.

• 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.

Defining pre-build rules can be done in the following style:

{-# LANGUAGE BlockArguments, StaticPointers #-}
myPreBuildRules :: PreBuildComponentRules
myPreBuildRules = rules (static ()) $ \ preBuildEnvironment -> do
  let cmd1 = mkCommand (static Dict) $ static \ arg -> do { .. }
      cmd2 = mkCommand (static Dict) $ static \ arg -> do { .. }
  myData <- liftIO someIOAction
  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 Rules, Rule and Command constructors, which insulates us from internal changes to the Rules, Rule and Command datatypes, respectively.

We use addRuleMonitors to declare a monitored directory that the collection of rules as a whole depends on. In this case, we declare that they depend on the contents of the "searchDir" directory. This means that the rules will be computed anew whenever the contents of this directory change. (This does not mean all the rules will be re-run; only the out-of-date rules will be re-run.)

Rule names (use OverloadedStrings or fromString)

The dynamicRule smart constructor allows specifying rules that have dynamic dependencies. This is the most complex part of the API, so let's work through a representative example.

Suppose for example that we have preprocessor for files that may depend on each other via explicit import statements at the start of the file. To properly preprocess these, we need two commands:

1. A "find dependencies" command that parses the header to find the dependencies.
2. A "run preprocessor" command. This command might need to be passed the dependencies as arguments, so the command in (1) should make that information available to (2).

This is exactly what dynamicRule allows us to do. The first command is (1), which returns dynamic dependencies and additional data passed to the second command, (2).

The rules for such a preprocessor would thus look something like (sketch):

ppDynPreBuildRules :: PreBuildComponentInputs -> RulesM ()
ppDynPreBuildRules pbci = mdo -- NB: using RecursiveDo

  -- Scan filesystem for files to preprocess, e.g. with a monitored file glob.
  inputModNms <- ...

  let

    -- (1): the "find dependencies" action
    computeDepsAction
      :: (Map ModuleName RuleId, FilePath)
      -> IO ([Dependency], [ModuleName])
    computeDepsAction (modNmToRuleId, inFile) = do
      src <- readFile inFile
      let dynDeps = parseHeaderImports src
      return
        ( [ RuleDependency $ RuleOutput rId 1
          | dep <- dynDeps
          , let rId = modNmToRuleId Map.! dep ]
        , dynDeps )

    -- (2): the "run preprocessor" action
    runPPAction :: (FilePath, FilePath) -> [ModuleName] -> IO ()
    runPPAction (inFile, outFile) dynDeps = do
      src <- readFile inFile
      let ppResult = preprocessWithDependencies dynDeps src
      writeFile outFile ppResult

    -- Construct a rule with dynamic dependencies using dynamicRule
    mkRule modNm =
      dynamicRule (static Dict)
        (mkCommand (static Dict) (static computeDepsAction) (allRuleIDs, inFile))
        (mkCommand (static Dict) (static runPPAction) (inFile, outFile))
        [ FileDependency $ Location sameDirectory (modPath . "myPp") ]
        ( Location autogenDir (modPath . "hs" )
        NE.:| [ Location buildDir (unsafeCoerceSymbolicPath modPath . "myPpIface") ] )
      where
        modPath = moduleNameSymbolicPath modNm
        inFile  = getSymbolicPath (sameDirectory / modPath . "myPp")
        outFile = getSymbolicPath (autogenDir    / modPath . "hs")

    autogenDir = ... -- derived from pbci
    buildDir   = ... -- derived from pbci

    registerOne :: ModuleName -> RulesM (ModuleName, RuleId)
    registerOne modNm = do
      rId registerRule ("MyPP: " < show modNm) (mkRule modNm)
      return (modNm, rId)

  -- Return a map from ModuleName to RuleId (used above via RecursiveDo).
  allRuleIDs Map.fromList <$ traverse registerOne inputModNms
  return ()

Note the usage of RecursiveDo to allow indexing into the set of all registered rules in order to declare the dynamic dependencies of the rules.

In this example we use tuples for the command arguments and [ModuleName] for the result of the dynamic dependency command; these have the required instances needed for serialisation. If you use custom datatypes for these, you will need to derive Binary, Show, Eq to satisfy the API requirements (enforced by the various calls to static Dict).

Rules can declare various kinds of dependencies:

• static dependencies: files or other rules that a rule statically depends on,
• extra dynamic dependencies, using dynamicRule smart constructor,
• MonitorFilePath: additional files and directories to monitor.

Rules are considered out-of-date precisely when any of the following conditions apply:

O1

there has been a (relevant) change in the files and directories monitored by the rules,

O2

the environment passed to the computation of rules has changed.

If the rules are out-of-date, the build system is expected to re-run the computation that computes all rules.

After this re-computation of the set of all rules, we match up new rules with old rules, by RuleId. A rule is then considered stale if any of following conditions apply:

N

the rule is new, or

S

the rule matches with an old rule, and either:

S1

a file dependency of the rule has been modified/created/deleted, or a (transitive) rule dependency of the rule is itself stale, or

S2

the rule is different from the old rule, e.g. the argument stored in the rule command has changed, or the pointer to the action to run the rule has changed. (This is determined using the Eq Rule instance.)

A stale rule becomes no longer stale once we run its associated action. The build system is responsible for re-running the actions associated with each stale rule, in dependency order. This means the build system is expected to behave as follows:

1. Any time the rules are out-of-date, query the rules to obtain up-to-date rules.
2. Re-run stale rules.

Cabal will execute all **demanded** rules in dependency order. A rule is demanded if it satisfies one of the following conditions:

1. It is a dependency of another demanded rule.
2. The rule generates a Haskell file declared in the autogen-modules field. In this case, the rule **must** place the generated source file in the autogenComponentModulesDir appropriate for the component.
3. (Since Cabal 3.18 only) The rule generates a non-Haskell source file, such as a C or JavaScript source. In this case (because there is no "autogen-c-sources" field), the following steps must be taken: a. Add the file to the 'c-sources' (or 'js-sources', etc) field of the package description in a per-component pre-configure hook, declaring it in the same autogenComponentModulesDir directory (as if it was a .hs file). b. Add a pre-build rule that generates the source file and puts it in this same autogenComponentModulesDir directory. Note that any file declared in the includes/'autogen-includes' fields must be present at **configure** time, so cannot be generated in a pre-build rule. In that case, either use a pre-configure hook or don't declare it under the includes field (if possible).
4. (Since Cabal 3.18 only) The rule generates an extra bundled library file, placed in the autogenComponentModulesDir and with a filename matching one of the libraries named in the 'extra-bundled-libraries' field (ignoring file extension).