git.iko.soy/haskell.nix
on iko/ghcjs-patch-master help sign in
Improve docs, mention pinning Hackage and Stackage (#668)

Fixes #536.

commitda9c5b93a983b03ed2c32c081915dda95cc6917c authorMichael Peyton Jones <michael.peyton-jones@iohk.io> dateWed 10 Jun 2020, 11:31 (6 years ago) parentd3bfa57
3 files changed+44−8
compare with iko/ghcjs-patch-master
unifiedsplit
README.md+9−8 docs/user-guide/hackage-stackage.md+34 mkdocs.yml+1
README.md+9−8
@@ -4,7 +4,7 @@
44[![](https://img.shields.io/buildkite/c8d5a20d3ff0f440f82adb9190b43c16c91e5e47e8adfa867a/master.svg?label=nightly%20updates)](https://buildkite.com/input-output-hk/haskell-dot-nix-nightly-updates)
55
66`haskell.nix` can automatically translate your Cabal or Stack project and
7−its dependencies into Nix code.
7+its dependencies into Nix code.
88
99## [Documentation](https://input-output-hk.github.io/haskell.nix/)
1010
@@ -70,6 +70,8 @@ pkgs.haskell-nix.stackProject {
7070}
7171```
7272
73+### Working with a project
74+
7375To build the library component of a package in the project run:
7476
7577```shell
@@ -90,24 +92,23 @@ cabal new-build your-package-name
9092cabal new-repl your-package-name:library:your-package-name
9193```
9294
93−## Using binary Cache to speed up compilation
95+## Using a binary cache
9496
9597To use precompiled binaries you'll need:
9698
97−- to configure a binary cache by following instructions on [iohk.cachix.org](https://iohk.cachix.org).
98−- to pin `nixpkgs` according to [nix/sources.json](nix/sources.json).
99−
99+- To configure the IOHK binary cache by following the instructions on [iohk.cachix.org](https://iohk.cachix.org).
100+- To pin your `nixpkgs` to match one of the revisions built by our CI: these can be found inside the `sources` attribute (see the quickstart above for an example).
100101
101102## Related repos
102103
103104The `haskell.nix` repository contains the runtime system for building
104105Haskell packages in Nix. It depends on other repos, which are:
105106
106−- [nix-tools](https://github.com/input-output-hk/nix-tools) — provides the programs for generating Nix expressions from Haskell projects.
107+- [`nix-tools`](https://github.com/input-output-hk/nix-tools) — provides the programs for generating Nix expressions from Haskell projects.
107108
108−- [hackage.nix](https://github.com/input-output-hk/hackage.nix) — the latest contents of the [Hackage](https://hackage.haskell.org/) databases, converted to Nix expressions.
109+- [`hackage.nix`](https://github.com/input-output-hk/hackage.nix) — the latest contents of the [Hackage](https://hackage.haskell.org/) databases, converted to Nix expressions.
109110
110−- [stackage.nix](https://github.com/input-output-hk/stackage.nix) — all of the [Stackage](https://www.stackage.org/) snapshots, converted to Nix expressions.
111+- [`stackage.nix`](https://github.com/input-output-hk/stackage.nix) — all of the [Stackage](https://www.stackage.org/) snapshots, converted to Nix expressions.
111112
112113## IRC Channel
113114
docs/user-guide/hackage-stackage.mdnew file+34
@@ -0,0 +1,34 @@
1+# Hackage and Stackage
2+
3+`haskell.nix` relies on some generated data providing information about packages in Hackage and Stackage snapshots.
4+These are kept in [`hackage.nix`](https://github.com/input-output-hk/hackage.nix) and [`stackage.nix`](https://github.com/input-output-hk/stackage.nix) respectively.
5+If your project depends on a Hackage package, then the `hackage.nix` revision used must be new enough to contain that, and likewise for Stackage snaphots and `stackage.nix`.
6+
7+## Updating and pinning `hackage.nix` and `stackage.nix`
8+
9+`haskell.nix` pins particular revisions of these repositories internally, both for our own usage in testing, and so that users have a sensible default when getting started.
10+These revisions are updated nightly, so you can get newer revisions of `hackage.nix` and `stackage.nix` by updating your revision of `haskell.nix` itself.
11+
12+However, this exposes you to changes in `haskell.nix` which you may not want, such as changes that force compiler rebuilds, or the occasional bug.
13+Instead, you can pin `hackage.nix` and `stackage.nix` independently. For example:
14+
15+```
16+let
17+ # You can use a tool like `niv` to manage this boilerplate
18+ hackageSrc = builtins.fetchTarball https://github.com/input-output-hk/hackage.nix/archive/master.tar.gz;
19+ stackageSrc = builtins.fetchTarball https://github.com/input-output-hk/stackage.nix/archive/master.tar.gz;
20+ haskellSrc = builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz;
21+
22+ haskellNix = import haskellSrc {
23+ # This allows you to override the pins used by `haskell.nix` internally
24+ sourcesOverride = {
25+ hackage = hackageSrc;
26+ stackage = stackageSrc;
27+ };
28+ };
29+in ...
30+```
31+
32+You can then change the revisions that `hackage.nix` and `stackage.nix` are fetched from without changing `haskell.nix`.
33+
34+However, bear in mind that Stackage refers to Hackage, so your Stackage should never be newer than Hackage.
mkdocs.yml+1
@@ -31,6 +31,7 @@ pages:
3131 - 'Creating Nix builds for your projects': user-guide/projects.md
3232 - 'Stack Projects': user-guide/stack-projects.md
3333 - 'Cabal Projects': user-guide/cabal-projects.md
34+ - 'Hackage and Stackage': user-guide/hackage-and-stackage.md
3435 - 'How to create a development environment': user-guide/development.md
3536 - 'How to cross-compile your project': user-guide/cross-compilation.md
3637 - 'Reference':