Skip to content

Commit 1250f04

Browse files
authored
Improve binary caching documentation, make more salient (#875)
People constantly ask about this, clearly without having found the documentation that we do have about this. So we need to make it more obvious: - Simplify the setup documentation to emphasize the Hydra cache (which is the only working one currently). - Move the cache troubleshooting section to the top to make it more obvious. - Highlight a link to the troubleshooting section of the docs in the README. - Emphasize that there is more documentation than is linked in the README. - Add a section to the README that explicitly mentions cache issues, and links to the corresponding sections of the docs.
1 parent 72d21e0 commit 1250f04

File tree

4 files changed

+47
-46
lines changed

4 files changed

+47
-46
lines changed

README.md

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,21 @@ its dependencies into Nix code.
1010

1111
- [Introduction](https://input-output-hk.github.io/haskell.nix/)
1212
- [Getting Started](https://input-output-hk.github.io/haskell.nix/tutorials/getting-started/)
13+
- [Troubleshooting](https://input-output-hk.github.io/haskell.nix/troubleshooting/)
14+
- Explore the documentation from there to find further topics.
15+
16+
## Help! Something isn't working
17+
18+
The #1 problem that people have when using `haskell.nix` is that they find themselves building GHC.
19+
This should not happen, but you *must* follow the `haskell.nix` setup instructions properly to avoid it.
20+
If you find this happening to you, please check that you have followed the
21+
[getting started instructions](https://input-output-hk.github.io/haskell.nix/tutorials/getting-started/#setting-up-the-binary-cache) and
22+
consult the corresponding [troubleshooting section](https://input-output-hk.github.io/haskell.nix/troubleshooting/#why-am-i-building-ghc).
23+
24+
The troubleshooting documentation also contains some help for other common issues.
25+
Please give it a read before asking on IRC or opening an issue.
26+
27+
If you're still stuck, join the [#haskell.nix](https://www.irccloud.com/invite?channel=%23haskell.nix&hostname=irc.freenode.net&port=6697&ssl=1) channel on [irc.freenode.net](https://freenode.net/), or open an issue.
1328

1429
## Related repos
1530

@@ -22,7 +37,3 @@ Haskell packages in Nix. It depends on other repos, which are:
2237

2338
- [`stackage.nix`](https://github.com/input-output-hk/stackage.nix) — all of the [Stackage](https://www.stackage.org/) snapshots, converted to Nix expressions.
2439

25-
## IRC Channel
26-
27-
Join the [#haskell.nix](https://www.irccloud.com/invite?channel=%23haskell.nix&hostname=irc.freenode.net&port=6697&ssl=1) channel on [irc.freenode.net](https://freenode.net/) to get help or discuss
28-
the development of `haskell.nix` and `nix-tools`.

docs/reference/supported-ghc-versions.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Supported GHC Versions
22

33
The following versions of GHC built on the CI servers and should be included
4-
in the cache (for the default haskell.nix `nixpkgs`).
4+
in the binary cache (for the default haskell.nix `nixpkgs`).
55

66
* 8.6.5 `compiler-nix-name = "ghc865";`
77
* 8.8.3 `compiler-nix-name = "ghc883";`
@@ -27,6 +27,4 @@ The following GHC versions are not included in CI and will not be cached:
2727
See [overlays/bootstrap.nix](https://github.com/input-output-hk/haskell.nix/blob/master/overlays/bootstrap.nix)
2828
for a list of all the valid `compiler-nix-names`.
2929

30-
See also:
31-
32-
* [Instructions on adding new GHC versions](../dev/adding-new-ghc.md).
30+
See also: [Instructions on adding new GHC versions](../dev/adding-new-ghc.md).

docs/troubleshooting.md

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,29 @@
11
# Troubleshooting
22

3+
## Issues with building and garbage-collection
4+
5+
### Why am I building GHC?
6+
7+
It's easier to list the reverse: when will you *not* build GHC?
8+
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).
12+
13+
If you think you are doing all of these and you still find you're building GHC, drop us a line.
14+
15+
### Why am I building lots of Haskell packages?
16+
17+
We don't generally cache much of Hackage (there's a lot of it!), except for the parts which are used by our tests.
18+
So this is expected, unfortunately.
19+
20+
### How do I prevent the evaluation-time dependencies of my project from being garbage-collected?
21+
22+
The `haskell-nix.roots "ghc884"` should include all the evaluation-time dependencies
23+
and the main build time dependencies of a project using ghc 8.8.4.
24+
So you can add that to the relevant GC root.
25+
In practice, if you're using a CI system like Hydra/Hercules, this means adding it to a job in `release.nix`/`ci.nix`.
26+
327
## General troubleshooting when using `cabalProject`/`stackProject`/`project`
428

529
### Does the cabal/stack build work?
@@ -46,27 +70,3 @@ Where possible, try to do the configuration in your cabal/stack configuration, e
4670
This will ensure that the two builds agree.
4771

4872
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 `haskell-nix.roots "ghc884"` should include all the evaluation-time dependencies
70-
and the main build time dependencies of a project using ghc 8.8.4.
71-
So you can add that to the relevant GC root.
72-
In practice, if you're using a CI system like Hydra/Hercules, this means adding it to a job in `release.nix`/`ci.nix`.

docs/tutorials/getting-started.md

Lines changed: 6 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,29 +8,21 @@ project and its dependencies into Nix code.
88
Assuming you have [Nix](https://nixos.org/download.html) installed, you can
99
start setting up your project.
1010

11-
## Setting up the Cachix binary cache
11+
## Setting up the binary cache
1212

13-
You can **avoid compiling GHC and nix-tools** by configuring
14-
[Cachix](https://cachix.org) so you can benefit from the binary cache built by
15-
CI:
13+
IMPORTANT: you *must* do this or you *will* build several copies of GHC!
1614

17-
```bash
18-
$ nix-env -iA cachix -f https://cachix.org/api/v1/install
19-
installing 'cachix-0.3.8'
20-
building '/nix/store/bh176xhpk4wrjm56iahm86wf85jaz23v-user-environment.drv'...
21-
created 42 symlinks in user environment
15+
You can configure Nix to use our binary cache, which is pushed to by CI, so should contain the artifacts that you need.
2216

23-
$ cachix use iohk
24-
Configured https://iohk.cachix.org binary cache in ~/.config/nix/nix.conf
25-
```
26-
27-
Note: `haskell.nix` currently uses multiple CI providers to build derivations and store outputs. To improve your chances of getting a cache hit, you might want to add the following additional substituter to `~/.config/nix/nix.conf`:
17+
You need to add the following sections to `/etc/nix/nix.conf` or, if you are a trusted user, `~/.config/nix/nix.conf` (if you don't know what a "trusted user" is, you probably want to do the former).
2818

2919
```
3020
trusted-public-keys = [...] hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= [...]
3121
substituters = [...] https://hydra.iohk.io [...]
3222
```
3323

24+
This can be tricky to get setup properly. If you're still having trouble getting cache hits, consult the corresponding [troubleshooting section](../reference/troubleshooting#why-am-i-building-ghc).
25+
3426
## Scaffolding
3527

3628
The following work with `stack.yaml` and `cabal.project` based

0 commit comments

Comments
 (0)