Lessons learned from Custom

[ezyang]

1. I think when Custom was originally written, the idea was that the custom Setup.hs scripts would always track the latest Cabal head. This optimism was unfounded, and we've only now added setup-depends to actually make it possible to make sure we don't actually try to build a Setup script against the wrong Cabal. But supporting Setup scripts built against old versions of Cabal is a HUGE backwards-compatibility burden, because it means we can't make improvements to the Cabal library and expect to get them for custom setup scripts. If we were to rewrite the Custom, we would try to expose as many of the hooks as external, out-of-process things (c.f. Proposal for a Cabal plugin API (inversion of control) #2395) so that you would NOT have to build against the Cabal library, and it would be easier to manage BC because we wouldn't be supporting a monolithic hook interface but a modular one. Yes, designing these interfaces is hard but we have a pretty good idea what people want to do these days.

2. The hook interface is fragile across versions of Cabal, because it was decided that each hook should take multiple arguments, and over time the architecture has evolved that these arguments are not accurate: in fact, the big change was the switch from per-package compilation to per-component compilation; most hooks still don't know what components they are being built for, which results in some more issues, c.f. LocalBuildInfo should change at build time when components are selected #2910. If you design a hook interface in the future, I think every hook should be given a type HookNameArgs -> IO (), where HookNameArgs is a per-hook, abstract data structure. This gives maximum flexibility for changing/updating/adding BC shims in the future. This is not a bug, it's a feature:

   -- TODO: this one should not be here, it's just that the silly
   -- UserHooks stop us from passing extra info in other ways
   buildArgs :: [String]
   

3. Stack builds a Setup executable (with the default) to invoke when it builds Cabal packages. So far so good. But then it doesn't necessarily use the latest version of Cabal to build this executable. BAD! This has meant that whenever there was a bug in Cabal, it was expedient for stack to work around it in stack rather than contribute a fix to Cabal. I don't know how to prevent this from happening in the future.