@@ -1,94 +1,15 @@
1# haskell.nix
1# haskell.nix
3−haskell.nix is an alternative Haskell infrastructure for nixpkgs. See
3+`haskell.nix` is an alternative Haskell infrastructure for Nix[^1].
4−[Nixpkgs current Users' Guide to Haskell Infrastructure][nixpkgs] for
7−[nixpkgs]: https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure
5+## Features
8−[issues]: https://github.com/input-output-hk/haskell.nix/issues
12−Why do we need another Haskell infrastructure for nix? Doesn't nixpkgs
13−provide a sufficiently good Haskell infrastructure already? These are
14−good questions. And it boils down to the following reasons for us to
15−embark on a new infrastructure:
17−- first class support for cross compilation
18−- first class support for package sets
19−- component level control when building packages
20−- reduction of `dontCheck` for cyclic dependencies
21−- reducing build times by building libraries and tests in parallel
22−- more logic encoded in nix expressions
23−- decoupling of Haskell and nixpkgs
27−`nixpkgs` has quite good support for cross compilation, however the
28−Haskell infrastructure suffers from the fact that it heavily relies on
29−the `cabal2nix` tool. `cabal2nix` (as well as tools that depend on it
30−like `stack2nix`) flattens the `.cabal` file at conversion time to a
31−given os/arch/flags configuration. Thus to make cross compilation
32−work with `cabal2nix` you will have to generate a separate `nix`
33−expression for each configuration. This becomes a major maintenance
34−burden over time. Therefore the tooling that translates cabal files
35−into nix-expressions for use with Haskell.nix retains the full
36−conditional tree from the cabal file and exposes it to `nix`. In
37−addition it will also expose the `build-type` value, which allows us
38−to cache the `Setup.hs` for build-type simple and not have to rebuild
43−We often rely on either package sets as provided by stackage or
44−computed by cabal. `nixpkgs` provides its own curated package set
45−which might or might not work for the projects we work on.
46−`stack2nix` tries to solve this issue, here we go one step further and
47−provide the infrastructure to allow any form of package set.
49−### component level control
7+- autogenerate Nix expressions for Cabal project
8+- autogenerate Nix expressions for Stack
9+- overridable configuration
51−The Haskell builder in `nixpkgs` provides control over executables and
12+[^1]: See [Nixpkgs current Users' Guide to Haskell Infrastructure][nixpkgs] for comparison.
52−libraries, to build a specific executable only however is rather
13+[nixpkgs]: https://nixos.org/nixpkgs/manual/#users-guide-to-the-haskell-infrastructure
53−tricky to do. This also leads to the cyclic dependencies issue.
55−### cyclic dependencies
57−The Haskell builder in `nixpkgs` exposes packages at the
58−package level. If packages mutually depend on each other through tests
59−and libraries, this leads to cyclic dependencies that nix can't resolve. By
60−exposing the components to nix as separate derivations this will only
61−occur if you have mutually dependent components.
65−The Haskell builder in nixpkgs builds a package sequentially, first the
66−library then the executables and finally the tests. It then executes
67−the tests before the package is considered done. The upshot of this
68−is that packages are only considered done if the test-suites
69−passed. The downside is that if you have to compile multiple packages
70−the likelihood of them failing is low, you have unnecessarily
71−serialized your build. In a more aggressive setting libraries could
72−start building as early as their dependent libraries are built. Of
73−course they will have to be invalidated later should the test-suites
74−of their dependencies fail, but this way we can make use of parallel
75−building. In an ideal scenario this will reduce build times close to
80−The `cabal2nix` tool has a resolver that resolves system dependencies
81−and licenses to values in `nixpkgs`. This logic ends up being a simple
82−dictionary lookup and therefore can be a simple nix expression. This also
83−offloads some of the work the cabal to nix translation tool needs to
84−do into nix, and as such if changes are necessary (or needed to be
85−performed ad hoc) there is no need to rebuild the conversion tool and
86−subsequently mark every derived expression as out of date.
90−Finally, by treating Haskell.nix and nixpkgs as separate entities we
91−can decouple the Haskell packages and infrastructure from the nixpkgs
92−package set, and rely on it to provide us with system packages while
93−staying up to date with Haskell packages from hackage while retaining
94−a stable (or known to be good) nixpkgs revision.