@@ -1,12 +1,48 @@
11# User Guide
22
3−So you want to use [Haskell.nix][] with your stack or cabal project. The
4−general approach will be to pick the right tool from `nix-tools` and
5−produce a `pkgs.nix` expression. Getting a copy of the `nix-tools`
6−(and potentially the [Haskell.nix][] source), will then equip us to
7−produce derivations that we can `nix build`.
3+[Haskell.nix][] can be use for two different use cases:
4+
5+1. to build a specific package from hackage or a [stackage][] lts or nightly set.
6+
7+ To build a package, say [lens][], from a stackage snapshot, say [lts-13.28][],
8+ you could run
9+ ```bash
10+ nix build '(with import ./. {}; snapshots."lts-13.28").lens.components.library'
11+ ```
12+ which would build the [lens][] library component from the lens package as fixed
13+ by the [lts-13.28][] stackage snapshot.
14+
15+ To build any package from hackage, say [lens][], in version, say 4.17.1, you
16+ could run
17+ ```bash
18+ nix build '(with import ./. {}; (hackage-package { name = "lens"; version = "4.17.1"; })).components.library'
19+ ```
20+ which would build the [lens][] library component from the [lens-4.17.1][] package
21+ from hackage. The dependencies would be solved against the most recent
22+ [hackage-index-state][] that comes via the [hackage.nix][] pin with your
23+ [haskell.nix][] checkout. A specific one can be specified as well:
24+ ```bash
25+ nix build '(with import ./. {}; (hackage-package { name = "lens"; version = "4.17.1"; index-state = "2019-07-14T00:00:00Z"; })).components.library'
26+ ```
27+ which would use the hackage index as of `2019-07-14T00:00:00Z` to produce a build plan
28+ for the [lens-4.17.1][] package.
29+
30+
31+2. to build a stack or cabal project.
32+
33+ So you want to use [Haskell.nix][] with your stack or cabal project. The
34+ general approach will be to pick the right tool from `nix-tools` and
35+ produce a `pkgs.nix` expression. Getting a copy of the `nix-tools`
36+ (and potentially the [Haskell.nix][] source), will then equip us to
37+ produce derivations that we can `nix build`.
838
939[haskell.nix]: https://github.com/input-output-hk/haskell.nix
40+[stackage]: https://stackage.org
41+[lts-13.28]: https://www.stackage.org/lts-13.28
42+[lens]: https://hackage.haskell.org/package/lens
43+[lens-4.17.1]: https://hackage.haskell.org/package/lens-4.17.1
44+[hackage.nix]: https://github.com/input-output-hk/hackage.nix
45+[hackage-index-state]: https://github.com/input-output-hk/hackage.nix/blob/master/index-state-hashes.nix
1046
1147## Installing `nix-tools`
1248