Cabal-2.0.1.0: A framework for packaging Haskell software

Safe Haskell | None
Language | Haskell2010

Distribution.Types.HookedBuildInfo

Synopsis

- type HookedBuildInfo = (Maybe BuildInfo, [(UnqualComponentName, BuildInfo)])
- emptyHookedBuildInfo :: HookedBuildInfo

# Documentation

type HookedBuildInfo = (Maybe BuildInfo, [(UnqualComponentName, BuildInfo)]) #

`HookedBuildInfo` is mechanism that hooks can use to override the `BuildInfo`s inside packages. One example use-case (which is used in core libraries today) is as a way of passing flags which are computed by a configure script into Cabal. In this case, the autoconf build type adds hooks to read in a textual `HookedBuildInfo` format prior to doing any operations.

Quite honestly, this mechanism is a massive hack since we shouldn't be editing the `PackageDescription` data structure (it's easy to assume that this data structure shouldn't change and run into bugs, see for example 1c20a6328579af9e37677d507e2e9836ef70ab9d). But it's a bit convenient, because there isn't another data structure that allows adding extra `BuildInfo` style things.

In any case, a lot of care has to be taken to make sure the `HookedBuildInfo` is applied to the `PackageDescription`. In general this process occurs in Distribution.Simple, which is responsible for orchestrating the hooks mechanism. The general strategy:

1. We run the pre-hook, which produces a `HookedBuildInfo` (e.g., in the Autoconf case, it reads it out from a file).
2. We sanity-check the hooked build info with `sanityCheckHookedBuildInfo`.
3. We update our `PackageDescription` (either freshly read or cached from `LocalBuildInfo`) with `updatePackageDescription`.

In principle, we are also supposed to update the copy of the `PackageDescription` stored in `LocalBuildInfo` at `localPkgDescr`. Unfortunately, in practice, there are lots of Custom setup scripts which fail to update `localPkgDescr` so you really shouldn't rely on it. It's not DEPRECATED because there are legitimate uses for it, but... yeah. Sharp knife. See https://github.com/haskell/cabal/issues/3606 for more information on the issue.

It is not well-specified whether or not a `HookedBuildInfo` applied at configure time is persistent to the `LocalBuildInfo`. The fact that `HookedBuildInfo` is passed to `confHook` MIGHT SUGGEST that the `HookedBuildInfo` is applied at this time, but actually since 9317b67e6122ab14e53f81b573bd0ecb388eca5a it has been ONLY used to create a modified package description that we check for problems: it is never actually saved to the LBI. Since `HookedBuildInfo` is applied monoidally to the existing build infos (and it is not an idempotent monoid), it could break things to save it, since we are obligated to apply any new `HookedBuildInfo` and then we'd get the effect twice. But this does mean we have to re-apply it every time. Hey, it's more flexibility.

emptyHookedBuildInfo :: HookedBuildInfo #