@@ -0,0 +1,71 @@
1+# Troubleshooting
2+
3+## General troubleshooting when using `cabalProject`/`stackProject`/`project`
4+
5+### Does the cabal/stack build work?
6+
7+In `haskell.nix`, we strive to take the build configuration from the cabal/stack configuration files.
8+So 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.
9+
10+So the first thing to do is make sure that the build works with `cabal` or `stack` as normal.
11+If it *does* work, then the `haskell.nix` one should as well.
12+If, 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).
13+
14+### Is the `haskell.nix` configuration completely in line with the cabal/stack configuration?
15+
16+The `haskell.nix` configuration can come apart from the cabal/stack configuration in a number of ways:
17+
18+#### Compiler version
19+
20+(Cabal users only. For stack users this comes from the snapshot, so stack and `haskell.nix` will agree.)
21+
22+The 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!).
23+Cabal 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).
24+Hence, the two can come apart.
25+
26+Make sure you are using the same compiler for the cabal build as for the `haskell.nix` build.
27+
28+#### Hackage index state
29+
30+(Cabal users only. For stack users, package versions come from the snapshot, so stack and `haskell.nix` will agree.)
31+
32+Cabal has the concept of the Hackage "index state".
33+This is a timestamp, and it tells Cabal to behave "as if" it was seeing Hackage at that point in time.
34+Pinning it is generally good for reproducibility regardless of whether you use `haskell.nix` (you can do so in `cabal.project`).
35+
36+If 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`.
37+These may not be the same!
38+So if you use `haskell.nix` we strongly recommend pinning the `index-state`.
39+
40+#### Nix-only configuration options
41+
42+You can set configuration options in your Nix code that are not present in the cabal/stack configuration.
43+For example, you might enable profiling.
44+
45+Where possible, try to do the configuration in your cabal/stack configuration, e.g. setting `profiling: true` in `cabal.project`.
46+This will ensure that the two builds agree.
47+
48+If you want or need to set some of them in Nix, try bringing the two into sync temporarily for troubleshooting.
49+
50+## Specific issues
51+
52+### Why am I building GHC?
53+
54+It's easier to list the reverse: when will you *not* build GHC?
55+
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).
59+
60+If you think you are doing all of these and you still find you're building GHC, drop us a line.
61+
62+### Why am I building lots of Haskell packages?
63+
64+We don't generally cache much of Hackage (there's a lot of it!), except for the parts which are used by our tests.
65+So this is expected, unfortunately.
66+
67+### How do I prevent the evaluation-time dependencies of my project from being garbage-collected?
68+
69+The `haskellNixRoots` attribute should include all the evaluation-time dependencies.
70+So you can add that to the relevant GC root.
71+In practice, if you're using a CI system like Hydra/Hercules, this means adding it to a job in `release.nix`/`ci.nix`.