git.iko.soy/haskell.nix
on 147cf21 help sign in
haskell.nix/docs/user-guide.md
198 lines 6.8 kB history raw
1# User Guide
3[Haskell.nix][] can be use for two different use cases:
51. to build a specific package from hackage or a [stackage][] lts or nightly set.
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.
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.
312. to build a stack or cabal project.
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`.
39[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
47## Installing `nix-tools`
49To build the latest `nix-tools` and store the result at `./nt`, run:
51```bash
52nix build -f https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz nix-tools --out-link nt
53```
55If you would like to then install `nix-tools` into your profile, run:
57```bash
58nix-env -i ./nt
59```
61## Getting the [Haskell.nix][] source (optional)
63The [Haskell.nix][] and `nix-tools` source will be useful if you would
64like to contribute improvements, or read the source code to fully
65understand something that the documentation doesn't cover.
67```bash
68git clone https://github.com/input-output-hk/nix-tools
69git clone https://github.com/input-output-hk/haskell.nix
70cd haskell.nix
71nix build -f . nix-tools --out-link nt
72```
74## Importing [Haskell.nix][] into your project
76The easiest way to get a hold of [Haskell.nix][] is with
77[`fetchTarball`](https://nixos.org/nix/manual/#ssec-builtins).
79```nix
80import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}
81```
83If you have your own `pkgs` variable, pass it to [Haskell.nix][] to
84prevent double-evaluation of the Nixpkgs collection.
86```nix
87{ pkgs ? import <nixpkgs> {} }:
89import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) { inherit pkgs; }
90```
92### Pinning the [Haskell.nix][] version
94For simplicity's sake we will use `fetchTarball` for the examples in
95this documentation. This will always get the latest version, and is
96similar to an auto-updating Nix channel.
98However, in your own project, you may wish to pin [Haskell.nix][] (as
99you would pin Nixpkgs). This will make your builds reproducable, more
100predictable, and faster (because the fixed version is cached).
102One way of doing this is to use `nix-prefetch-git` to get a JSON file
103with a revision and SHA-256 hash of [Haskell.nix][].
105```
106$ nix-prefetch-git --quiet https://github.com/input-output-hk/haskell.nix | tee haskell-nix-src.json
108 "url": "https://github.com/input-output-hk/haskell.nix",
109 "rev": "f1a94a4c82a2ab999a67c3b84269da78d89f0075",
110 "date": "2019-06-05T01:06:12+00:00",
111 "sha256": "0ggxsppjlb6q6a83y12cwgrdnqnw1s128rpibgzs5p1966bdfqla",
112 "fetchSubmodules": false
114```
116(The `tee` command is just to show you the result.)
117Use the following expression to import that version:
119```nix
120{ pkgs ? import <nixpkgs> {} }:
122let
123 spec = builtins.fromJSON (builtins.readFile ./haskell-nix-src.json);
124 haskell-nix-src = pkgs.fetchgit {
125 name = "haskell-lib";
126 inherit (spec) url rev sha256 fetchSubmodules;
127 };
128in
129 import haskell-nix-src { inherit pkgs; }
130```
132There are other possible schemes for pinning. See
133[`haskell.nix/lib/fetch-external.nix`](https://github.com/input-output-hk/haskell.nix/blob/master/lib/fetch-external.nix),
134the [niv](https://github.com/nmattia/niv) tool, or the Nix Flakes
135proposal.
137### Overriding the Hackage version
139Sometimes you might want to use a chosen version of Haskell.nix with a
140recent update of Hackage or Stackage. This can be done with JSON pins:
142```bash
143nix-prefetch-git https://github.com/input-output-hk/hackage.nix | tee hackage-src.json
144nix-prefetch-git https://github.com/input-output-hk/stackage.nix | tee stackage-src.json
145```
147The resulting JSON files will correspond to the latest revision of
148[hackage.nix][] and [stackage.nix][]. See
149[Architecture](architecture.md) for more information about how
150these Git repositories correspond to the actual Hackage and Stackage.
152[hackage.nix]: https://github.com/input-output-hk/hackage.nix
153[stackage.nix]: https://github.com/input-output-hk/stackage.nix
155```nix
156{ pkgs ? import <nixpkgs> {} }:
158import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {
159 inherit pkgs;
160 hackageSourceJSON = ./hackage-src.json;
161 stackageSourceJSON = ./stackage-src.json;
163```
165## Using `nix repl`
167It's sometimes useful to load [Haskell.nix][] in the REPL to explore
168attrsets and try examples.
170```
171# example.nix
172{ pkgs ? import <nixpkgs> {} }:
173rec {
174 haskell = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) { inherit pkgs; };
175 pkgNames = pkgs.lib.attrNames haskell.snapshots."lts-13.18";
177```
179Load the example file:
181```
182$ nix repl '<nixpkgs>' example.nix
183Welcome to Nix version 2.3pre6631_e58a7144. Type :? for help.
185Loading '<nixpkgs>'...
186Added 10403 variables.
188Loading 'example2.nix'...
189Added 2 variables.
191nix-repl> lib.take 5 pkgNames
192[ "ALUT" "ANum" "Allure" "Boolean" "BoundedChan" ]
194nix-repl>
195```
197Now that you have `nix-tools` and are able to import [Haskell.nix][],
198you can continue to the next chapter.