PSA for Cabal 2.2 new-* users regarding .ghc.environment files

[Gershom B]

There is an important change in the cabal new- commands for 2.2 that
the release docs should have highlighted more significantly.

Cabal new-* commands now produce a .ghc.environment file by default.
These files [1] are picked up by ghc and ghci automatically (since
8.0.1), and allow them to operate directly with the same package
environment used by the new-* commands. This lets you, for example,
run `ghci` in a project where you are using `new-build` and get the
proper dependencies in scope. Herbert has written an experimental tool
to make it easier to create and manipulate these environments [2].

However: there is a drawback (on which some discussion at [3] and [4].
In particular, there is not good information provided by ghc about
when these files are picked up and used. So if you are admixing new-*
commands and other commands for the time being, jumping between the
two, or admixing ghc and ghcjs, etc., then you may run into unexpected
behavior! [5] The simplest solution for now is to delete the local
.ghc.environment file in those cases (i.e. where you're mixing
commands and get unexpected behavior). A particular gotcha is that
these files are picked up not just in the current directory but also
in any parent directory.

Cheers,
Gershom


[1] documented at
https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/packages.html#package-environments
[2] https://github.com/hvr/cabal-env
[3] https://github.com/haskell/cabal/issues/4542
[4] https://ghc.haskell.org/trac/ghc/ticket/13753
[5] Error messages may be like
".cabal/store/ghc-8.0.2/package.db/package.cache: openBinaryFile: does
not exist (No such file or directory)" or complaints about missing
inplace dependencies.