Documentation

HookedBuildInfo is mechanism that hooks can use to override the BuildInfos 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.