git.iko.soy/haskell.nix
on f413621 help sign in
haskell.nix/docs/troubleshooting.md
72 lines 3.9 kB history raw
1# Troubleshooting
3## General troubleshooting when using `cabalProject`/`stackProject`/`project`
5### Does the cabal/stack build work?
7In `haskell.nix`, we strive to take the build configuration from the cabal/stack configuration files.
8So if you have a problem with your cabal/stack configuration, it is likely that you will have a problem with the `haskell.nix` build too.
10So the first thing to do is make sure that the build works with `cabal` or `stack` as normal.
11If it *does* work, then the `haskell.nix` one should as well.
12If, on the other hand, there is a failure, the `cabal` or `stack` build is usually easier to debug (or at least it is no longer a `haskell.nix` problem).
14### Is the `haskell.nix` configuration completely in line with the cabal/stack configuration?
16The `haskell.nix` configuration can come apart from the cabal/stack configuration in a number of ways:
18#### Compiler version
20(Cabal users only. For stack users this comes from the snapshot, so stack and `haskell.nix` will agree.)
22The compiler version used by `haskell.nix` is selected by the `compiler-nix-name` argument; or if you do not specify it, by some default version (we recommend specifying it!).
23Cabal does not provide an easy way to pin a *version* of the compiler (`with-compiler` lets you pick a particular executable, which is nearly but not quite what we want).
24Hence, the two can come apart.
26Make sure you are using the same compiler for the cabal build as for the `haskell.nix` build.
28#### Hackage index state
30(Cabal users only. For stack users, package versions come from the snapshot, so stack and `haskell.nix` will agree.)
32Cabal has the concept of the Hackage "index state".
33This is a timestamp, and it tells Cabal to behave "as if" it was seeing Hackage at that point in time.
34Pinning it is generally good for reproducibility regardless of whether you use `haskell.nix` (you can do so in `cabal.project`).
36If you do not set an `index-state` in `cabal.project`, then Cabal will use the latest one based on when you last called `cabal update`, and `haskell.nix` will use the latest one it knows about from `hackage.nix`.
37These may not be the same!
38So if you use `haskell.nix` we strongly recommend pinning the `index-state`.
40#### Nix-only configuration options
42You can set configuration options in your Nix code that are not present in the cabal/stack configuration.
43For example, you might enable profiling.
45Where possible, try to do the configuration in your cabal/stack configuration, e.g. setting `profiling: true` in `cabal.project`.
46This will ensure that the two builds agree.
48If you want or need to set some of them in Nix, try bringing the two into sync temporarily for troubleshooting.
50## Specific issues
52### Why am I building GHC?
54It's easier to list the reverse: when will you *not* build GHC?
56- You have configured the [binary caches](tutorials/getting-started.md) correctly.
57- You are using one of the GHC versions built by our CI (have a look in [ci.nix](../ci.nix) to see what gets built).
58- You are using one of the nixpkgs versions used by our CI (you can access the sources for these [through haskell.nix](tutorials/getting-started.md).
60If you think you are doing all of these and you still find you're building GHC, drop us a line.
62### Why am I building lots of Haskell packages?
64We don't generally cache much of Hackage (there's a lot of it!), except for the parts which are used by our tests.
65So this is expected, unfortunately.
67### How do I prevent the evaluation-time dependencies of my project from being garbage-collected?
69The `haskell-nix.roots "ghc884"` should include all the evaluation-time dependencies
70and the main build time dependecies of a project using ghc 8.8.3.
71So you can add that to the relevant GC root.
72In practice, if you're using a CI system like Hydra/Hercules, this means adding it to a job in `release.nix`/`ci.nix`.