git.iko.soy/haskell.nix
on e94de40 help sign in
haskell.nix/docs/troubleshooting.md
90 lines 4.9 kB history raw
1# Troubleshooting
3## Issues with building and garbage-collection
5### Why am I building GHC?
7It's easier to list the reverse: when will you *not* build GHC?
9- You have configured the [binary cache](tutorials/getting-started.md) correctly.
10- You are using one of the GHC versions which [we support](reference/supported-ghc-versions.md).
11- 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).
13If you think you are doing all of these and you still find you're building GHC, drop us a line.
15### Why am I building lots of Haskell packages?
17We don't generally cache much of Hackage (there's a lot of it!), except for the parts which are used by our tests.
18So this is expected, unfortunately.
20### How do I prevent the evaluation-time dependencies of my project from being garbage-collected?
22The `haskell-nix.roots "ghc884"` should include all the evaluation-time dependencies
23and the main build time dependencies of a project using ghc 8.8.4.
24So you can add that to the relevant GC root.
25In practice, if you're using a CI system like Hydra/Hercules, this means adding it to a job in `release.nix`/`ci.nix`.
27## General troubleshooting when using `cabalProject`/`stackProject`/`project`
29### Does the cabal/stack build work?
31In `haskell.nix`, we strive to take the build configuration from the cabal/stack configuration files.
32So 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.
34So the first thing to do is make sure that the build works with `cabal` or `stack` as normal.
35If it *does* work, then the `haskell.nix` one should as well.
36If, 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).
38### Is the `haskell.nix` configuration completely in line with the cabal/stack configuration?
40The `haskell.nix` configuration can come apart from the cabal/stack configuration in a number of ways:
42#### Compiler version
44(Cabal users only. For stack users this comes from the snapshot, so stack and `haskell.nix` will agree.)
46The 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!).
47Cabal 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).
48Hence, the two can come apart.
50Make sure you are using the same compiler for the cabal build as for the `haskell.nix` build.
52#### Hackage index state
54(Cabal users only. For stack users, package versions come from the snapshot, so stack and `haskell.nix` will agree.)
56Cabal has the concept of the Hackage "index state".
57This is a timestamp, and it tells Cabal to behave "as if" it was seeing Hackage at that point in time.
58Pinning it is generally good for reproducibility regardless of whether you use `haskell.nix` (you can do so in `cabal.project`).
60If 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`.
61These may not be the same!
62So if you use `haskell.nix` we strongly recommend pinning the `index-state`.
64#### Nix-only configuration options
66You can set configuration options in your Nix code that are not present in the cabal/stack configuration.
67For example, you might enable profiling.
69Where possible, try to do the configuration in your cabal/stack configuration, e.g. setting `profiling: true` in `cabal.project`.
70This will ensure that the two builds agree.
72If you want or need to set some of them in Nix, try bringing the two into sync temporarily for troubleshooting.
74## Other specific issues
76### Why does the build complain about some files being missing?
78Sometimes your build works fine outside `haskell.nix`, but inside the `haskell.nix` build, cabal complains that some file is missing.
79What is going on?
81The answer is that `haskell.nix` *thoroughly* cleans the source *by following what is mentioned as required in the cabal file*.
82So we only include Haskell sources if they appear in a `hs-source-dirs` somewhere; and we only include non-Haskell files if they are included in `extra-source-files` or similar.
84This is good practice anyway: if you do not include such files in `extra-source-files` then they will not be included in `cabal sdist`, which will cause problems if you ever upload your package to Hackage.
85But `haskell.nix` is very picky about it.
87### Why does my executable depend on GHC/GCC?
89You may want to set the `dontStrip` option to `false` (see https://github.com/input-output-hk/haskell.nix/issues/829).
90This is not set by default because it can occasionally cause breakage.