Proposal for a Cabal plugin API (inversion of control)

[bitemyapp]

doctest and ghc-mod are particularly emblematic of stuff that is awesome, but frequently breaks for various reasons. Some of that could be ameliorated with better tool integration.

ghc-mod has to be linked against the version of Cabal in the project otherwise it won't work properly.

/cc @ttuegel

[ttuegel]

I didn't think of this when we first discussed making a plugin API, but part of this issue would be solved by making it easier for library consumers to drive the entire configure/build process. That doesn't make sense for a tool like doctest (or maybe it does, and I don't understand that workflow). But I think it would make more sense for ghc-mod to call configure, build, etc. itself. Basically, the API should be so easy to use, no one hesitates to make a cabal-install-like command. That means we need to expose some of cabal-install's functionality, see #1848.

[bitemyapp]

@ttuegel have you looked at doctest's source? It's sorrowfully hacky. I'm not sure how it could be better done without tool/API support though.

[DanielG]

+1 for exposing more of cabal-install as a library. While a plugin system might be the better solution in the long run just being able to access some of the internals of cabal-install would already lift quite some burdens. I don't think it would fix the problems when different Cabal versions are in use by ghc-mod and the cabal-install executable on the users' PATH. See https://github.com/DanielG/cabal-helper for how we deal with that now.

[ttuegel]

Although I still think there is great value in making it easier for external agents to drive the configure-build-test-install process, I realized recently that we already have most of the machinery needed to implement a simpler, yet still powerful, plugin model.

The setup-depends work solves many of the problems with build-type: Custom, but your project is still tightly coupled to the Cabal API. External programs using the Cabal API have the same problem. The difficulties here are not insurmountable and are often outweighed by the tremendous power using the API gives you. But I think there is a big unexploited niche for solutions that need only a fraction of the power.

Consider our build-type: Configure, which allows a configuration script to output build info stanzas for the package description. I suggest we implement an architecture where plugins are executable programs which take a package description as text through stdin and output the modified description as text through stdout. (We could augment this later to allow plugins to modify different phases.)

Presumably, plugins would still link to the Cabal library to parse the package description, but it matters much less that the versions match because package descriptions are generally parseable between many versions. (Although, we would probably need some parser improvements here.)

For example, for automatic discovery of doctest tests, a package author could specify

configure-plugin: doctest-discover (doctest-discover >= 0.1)

and during configuration the package description could be modified by that executable to add the discovered tests.

This is just a rough sketch so far, but what do we think?

[ezyang]

To be clear, there are two things you might be referring to package description: the literal Cabal file (which can be parsed into GenericPackageDescription), or the description with conditionals resolved (PackageDescription). The latter's Binary/Show/Read serialization is NOT stable across versions. The former is insufficient for most plugins, who want the configured package.

[ttuegel]

I mean the literal Cabal file. I realize this is not enough for some of the plugins currently in existence, but I think there is a big, unexploited space of potential plugins that don't exist because the cost of integrating with the Cabal API is too high. I think the doctest-discover example I gave captures that well: at the moment, it operates as a GHC preprocessing stage because it would be unnecessary difficult to integrate with Cabal. I think something like this would also be relevant to your recent effort to clean up the PackageTests. This isn't enough power to implement something like ghc-mod, but I think it's a useful subset of functionality for a tiny fraction of the cost. I think this would also give us a good proof of concept if we wanted to offer a similar plugin interface for other phases, too.

[ttuegel]

Oh, I should also point out: there is nothing stopping us from using the literal Cabal file format for a textual representation of the package description even after all the conditionals have been resolved. And of course the Read/Show/Binary instances are too fragile for this.

[ezyang]

Yes, that's true.

I was under the impression that most plugins are also going to want access to LocalBuildInfo, but I haven't actually checked.