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 SetupHooks for more details.

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

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 $sel:preConfPackageHook:ConfigureHooks.
• All modifications to component configuration options must use $sel:preConfComponentHook:ConfigureHooks.

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.

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. To do so, registering a Rule with the API returns a unique identifier for that rule, in the form of a 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.

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

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.