@@ -1,28 +1,49 @@
11# Supported GHC Versions
22
3−
4−The following GHC versions are defined in `haskell.nix` (i.e. there is a derivation for them even if it isn't necessarily cached):
3+The following GHC versions are defined in `haskell.nix` (there is a derivation
4+for each, though not all are cached or tested by CI):
55- 8.4.4
66- 8.6.{1,2,3,4,5}
77- 8.8.{1,2,3,4}
8−- 8.10.{1,2,3,4}
8+- 8.10.{1,2,3,4,5}
9+- 9.0.1
10+
11+The following table shows the Nixpkgs/GHC versions which are built/cached, and
12+which of those are further tested. If you use a combination of Nixpkgs version
13+and GHC version which is in this table, you should hit our cache, saving
14+considering time by not building GHC and a few additional tools.
15+
16+Note that if you try to use `haskell.nix` as an overlay over Nixpkgs from a
17+standard Nixpkgs channel you will likely get a cache miss. To hit our cache you
18+really should use an instance of Nixpkgs provided by `haskell.nix` itself.
919
10−The following table shows the nixpkgs/GHC versions which are built by CI, and which of those are tested.
11−If you use a combination of nixpkgs version and GHC version which is in this table, you should get cache hits from our cache.
12−The "nixpkgs versions" refer to the versions that `haskell.nix` provides; if you use your own version of nixpkgs you will likely not get cache hit.
20+| Nixpkgs version | Nixpkgs pinning | GHC version | `compiler-nix-name` | Tested in CI? |
21+|------------------|--------------------|-------------|-----------------------|---------------|
22+| 20.09 | `nixpkgs-2009` | 8.6.5 | `ghc865` | No |
23+| 20.09 | `nixpkgs-2009` | 8.10.5 | `ghc8105` | No |
24+| 21.05 | `nixpkgs-2105` | 8.6.5 | `ghc865` | No |
25+| 21.05 | `nixpkgs-2105` | 8.10.5 | `ghc8105` | Yes |
26+| unstable | `nixpkgs-unstable` | 8.6.5 | `ghc865` | No |
27+| unstable | `nixpkgs-unstable` | 8.8.4 | `ghc884` | No |
28+| unstable | `nixpkgs-unstable` | 8.10.4 | `ghc8104` | No |
29+| unstable | `nixpkgs-unstable` | 8.10.5 | `ghc8105` | Yes |
30+| unstable | `nixpkgs-unstable` | 9.0.1 | `ghc901` | Yes |
1331
14−| Nixpkgs version | GHC version | Tested? |
15−|------------------|-------------|---------|
16−| 20.03 | 8.6.5 | Y |
17−| 20.09 | 8.6.5 | Y |
18−| 20.09 | 8.8.4 | Y |
19−| 20.09 | 8.10.4 | Y |
20−| nixpkgs-unstable | 8.6.5 | Y |
21−| nixpkgs-unstable | 8.8.4 | Y |
22−| nixpkgs-unstable | 8.10.4 | Y |
32+See [ci.nix](https://github.com/input-output-hk/haskell.nix/blob/master/ci.nix)
33+for the source of truth about what is built and tested (in the off chance this
34+document is out-of-sync with your checkout).
2335
24−See [ci.nix](https://github.com/input-output-hk/haskell.nix/blob/master/ci.nix) for the source of truth about what is built and tested.
36+See the [getting started guide](../tutorials/getting-started.md) for
37+instructions on how to set up Nix to take advantage of our cache when building.
38+This guide also covers where to use the Nixpkgs pinning and `compiler-nix-name`
39+settings from the table above. For further information, see the [instructions
40+for how to pin Nixpkgs](../dev/nixpkgs-pin.md).
2541
26−See [overlays/bootstrap.nix](https://github.com/input-output-hk/haskell.nix/blob/master/overlays/bootstrap.nix) for a list of all the valid `compiler-nix-names`.
42+See
43+[overlays/bootstrap.nix](https://github.com/input-output-hk/haskell.nix/blob/master/overlays/bootstrap.nix)
44+for a full list of all the valid `compiler-nix-name`s beyond what's
45+cached/tested in CI. You're free to use these, but be ready for longer build
46+times.
2747
28−See also: [Instructions on adding new GHC versions](../dev/adding-new-ghc.md).
48+Lastly, see [instructions on adding new GHC versions](../dev/adding-new-ghc.md)
49+in the event that what's in `haskell.nix` doesn't suit your needs.