Setup hooks

[sheaf]

This work-in-progress PR contains the implementation of the new Hooks build-type, as described in the Haskell Foundation Tech Proposal.

It builds on several previous PRs. For review, you should only need to look at the Introduce SetupHooks and SetupHooks: add tests commits.

New modules:

• Distribution.Simple.SetupHooks.Internal contains the internal implementation details of the API for the Hooks build type
• Distribution.Simple.SetupHooks.Rule defines fine grained rules as specified in the proposal, for use in pre-build hooks
• Distribution.Simple.SetupHooks.Errors defines error constructors pertaining to the Hooks build type

There are barely any changes to Cabal outside the introduction of these modules. Essentially, the changes consist of defining defaultMainWithSetupHooksArgs, and the introduction of variants build_setupHooks, configure_setupHooks... of existing functions (with e.g. build = build_setupHooks noBuildHooks) which insert the hooked actions at the appropriate times.

New libraries:

• Cabal-hooks is a new package that exports the exposed interface for package authors to write their own SetupHooks.hs modules. For the time being, it mostly re-exports datatypes from Cabal, together with some slightly higher-level functions for use in the API, all through the single module Distribution.Simple.SetupHooks. As explained in the HF tech proposal, a possible future goal would be to make this package no longer depend on Cabal, perhaps making Cabal depend on it instead. This would limit the amount of internal details from Cabal we are exposing through the Hooks API, which would have the potential to improve maintainability of user packages relying on the Hooks API.

TODO:

• [x] Rebase this PR once preparatory MRs land.
• [x] Update this PR once the discussion on the tech proposal settles down, with a final design.
• [x] Ensure all documentation is up-to-date relative to the exposed API.
• [x] Add changelog entry.
• [x] Address the remaining SetupHooks TODOs in the code.

--

[andreabedini]

:eyes: Thank you for opening this @sheaf! Edit: On a cursory look, it seems that choosing where to put code between Cabal and Cabal-hooks is not simple.

[sheaf]

I have rebased this MR, updated the API to make use of recent refactors (such as the refactor to file globbing in e2019f5a90213b8e8805f0e06fbe06227ebc5614), updated the documentation, and added a changelog entry.

I now consider this MR ready to review. Please refer to the OP for salient changes, as well as the HF tech proposal for an overview.

[sheaf]

Note that this includes PR #9518, which should be merged before this PR.

[Edit by Mikolaj: that PR has already been merged.]

[alt-romes]

@gbaz given your expertise here and your active participation in the design discussion we were hoping you could review the implementation MR. Let us know if anything needs clarification.

[alt-romes]

I've rebased the MR. It should be ready to merge again.

@gbaz would you be able to take a cursory look at this in a near future?

[gbaz]

Not a blocker but we should have a PR to update the user guide once this merges as well.

[andreabedini]

@gbaz It should be a blocker but the checkbox

Ensure all documentation is up-to-date relative to the exposed API.

is ticked; so I assume this has been done?

[sheaf]

@gbaz It should be a blocker but the checkbox

Ensure all documentation is up-to-date relative to the exposed API.

is ticked; so I assume this has been done?

No, that checkbox was only meant to track that the Haddocks were up-to-date w.r.t. the implementation. The user's guide has not been updated; I will do so promptly (as part of this PR).

Gershom, thanks for taking a look. I agree about guarding Hooks on Cabal version, I will do that as well.

[sheaf]

I have updated the user's guide and addressed the review. Note that the user's guide contains links to pages that don't exist yet, e.g. this Hackage page which will only exist once we upload Cabal-hooks to Hackage. I hope that's okay.

[alt-romes]

Thank you for your reviews @gbaz @andreabedini.

We're finishing the migration of packages in the testing-overlay to this very latest versions of Hooks to ensure there is nothing missing from this final version of the MR. We'll do the merge right after.

[sheaf]

I've been applying a few fixes, in particular to the Binary instances of datatypes involved in pre-build rule. The main point is that we want to be able to treat arguments to rules as opaque blobs of data on the build system side, which means that any such data must always be prefaced by its length (otherwise the build system doesn't know how much data to read). I am planning to get this merged as soon as CI passes now.

[ulysses4ever]

This is a big feature. Would it be okay for it to wait until cabal-install-3.14? Or does it call for an exception in our conservative backporting strategy? @Mikolaj? @sheaf? @alt-romes? @andreabedini?

[geekosaur]

I would wait.

[ulysses4ever]

Yeah, on today's Cabal call we decided to wait.