Tracking bug for cabal.project semantics

[ezyang]

There isn't any documentation for cabal.project, and it mostly does what people expect, except when it doesn't. So there are two problems: (1) there needs to be documentation saying exactly what cabal.project is supposed to do, and (2) the behavior needs to be set to match.

Here are the bugs:

• Specifying flags for all non-local packages in cabal.project #3719 - How to specify options for ALL transitive dependencies (not just inplace or local packages)
• new-build can't "undo" a build flag and build without the flag #3681 - How to pass --extra-include-dirs when building HsOpenSsl? (I think the root cause is HsOpenSsl is not inplace, configurations don't apply to it.)
• Package sections in cabal.project are insufficient, need local section #3579 - Package field applies even to NON inplace packages (So, maybe the semantics are that if you put it in packages it applies even to non-inplace thing?)
• --enable-profiling not recognized by new-build? #3442 - Profiling doesn't work
• [nix-local-build] Flag application to local packages, --disable-optimization and vendoring #3334 - Top-level flags to new-build apply to local packages, NOT inplace packages
• --extra-lib-dirs and --extra-include-dirs ignored? #2997 - People expect top-level flags to apply to dependencies, but they don't actually
• ghc-options applies to all dependencies, not just local packages #3883 - BUT program-options apply to ALL packages
• GHC incorrectly concludes rebuild unnecessary, even when ghc-options have changed #3891 - See @phadej's comment lower down; ghc-options needs to be partitioned into "affects hashing" and "doesn't affect hashing" flags.

General patterns I'm seeing:

• People are used to saying cabal install FLAGS and having FLAGS apply to all the dependencies which are being built. (Specifying flags for all non-local packages in cabal.project #3719, --extra-lib-dirs and --extra-include-dirs ignored? #2997, new-build can't "undo" a build flag and build without the flag #3681) new-build works differently: it NEVER applies the flags to transitive dependencies. This is actually what you want, because if the flags applies to all transitive dependencies, you would end up rebuilding the world every time you specified, e.g., a different --extra-include-dirs. But it's slightly unintuitive behavior, and worth warning about.
• Even if that's not what you want by default, there should be a way to specify an operation on all transitive dependencies (a case when you really do want to rebuild the world.) ([nix-local-build] Flag application to local packages, --disable-optimization and vendoring #3334)
• There is a distinction between a local package (one which you listed in packages) and an inplace package (any package which transitively depends on a local package). For example, in Cabal itself, hackage-security is NOT a local package, but it is an inplace package (as it depends on Cabal). The semantics for many operations are murky on whether or not they apply to inplace or local.
• There is not a way to specify a per-package operation ONLY on inplace/local packages; it always applies to all copies of the package (Package sections in cabal.project are insufficient, need local section #3579)

CC @dcoutts

[dcoutts]

Yes, important. Will review and give my thoughts.

[ezyang]

Milestoned for 2.0, because 2.0 is probably the last window when we can make BC-breaking changes to the cabal.project format. After that will likely be too long.

[ezyang]

Pinging @dcoutts for more thoughts on the issue.