git.iko.soy/haskell.nix
on 2e49d28 help sign in
haskell.nix/docs/user-guide.md
162 lines 5.1 kB history raw
1# User Guide
3So you want to use [Haskell.nix][] with your stack or cabal project. The
4general approach will be to pick the right tool from `nix-tools` and
5produce a `pkgs.nix` expression. Getting a copy of the `nix-tools`
6(and potentially the [Haskell.nix][] source), will then equip us to
7produce derivations that we can `nix build`.
9[haskell.nix]: https://github.com/input-output-hk/haskell.nix
11## Installing `nix-tools`
13To build the latest `nix-tools` and store the result at `./nt`, run:
15```bash
16nix build -f https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz nix-tools --out-link nt
17```
19If you would like to then install `nix-tools` into your profile, run:
21```bash
22nix-env -i ./nt
23```
25## Getting the [Haskell.nix][] source (optional)
27The [Haskell.nix][] and `nix-tools` source will be useful if you would
28like to contribute improvements, or read the source code to fully
29understand something that the documentation doesn't cover.
31```bash
32git clone https://github.com/input-output-hk/nix-tools
33git clone https://github.com/input-output-hk/haskell.nix
34cd haskell.nix
35nix build -f . nix-tools --out-link nt
36```
38## Importing [Haskell.nix][] into your project
40The easiest way to get a hold of [Haskell.nix][] is with
41[`fetchTarball`](https://nixos.org/nix/manual/#ssec-builtins).
43```nix
44import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}
45```
47If you have your own `pkgs` variable, pass it to [Haskell.nix][] to
48prevent double-evaluation of the Nixpkgs collection.
50```nix
51{ pkgs ? import <nixpkgs> {} }:
53import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) { inherit pkgs; }
54```
56### Pinning the [Haskell.nix][] version
58For simplicity's sake we will use `fetchTarball` for the examples in
59this documentation. This will always get the latest version, and is
60similar to an auto-updating Nix channel.
62However, in your own project, you may wish to pin [Haskell.nix][] (as
63you would pin Nixpkgs). This will make your builds reproducable, more
64predictable, and faster (because the fixed version is cached).
66One way of doing this is to use `nix-prefetch-git` to get a JSON file
67with a revision and SHA-256 hash of [Haskell.nix][].
69```
70$ nix-prefetch-git --quiet https://github.com/input-output-hk/haskell.nix | tee haskell-nix-src.json
72 "url": "https://github.com/input-output-hk/haskell.nix",
73 "rev": "f1a94a4c82a2ab999a67c3b84269da78d89f0075",
74 "date": "2019-06-05T01:06:12+00:00",
75 "sha256": "0ggxsppjlb6q6a83y12cwgrdnqnw1s128rpibgzs5p1966bdfqla",
76 "fetchSubmodules": false
78```
80(The `tee` command is just to show you the result.)
81Use the following expression to import that version:
83```nix
84{ pkgs ? import <nixpkgs> {} }:
86let
87 spec = builtins.fromJSON (builtins.readFile ./haskell-nix-src.json);
88 haskell-nix-src = pkgs.fetchgit {
89 name = "haskell-lib";
90 inherit (spec) url rev sha256 fetchSubmodules;
91 };
92in
93 import haskell-nix-src { inherit pkgs; }
94```
96There are other possible schemes for pinning. See
97[`haskell.nix/lib/fetch-external.nix`](https://github.com/input-output-hk/haskell.nix/blob/master/lib/fetch-external.nix),
98the [niv](https://github.com/nmattia/niv) tool, or the Nix Flakes
99proposal.
101### Overriding the Hackage version
103Sometimes you might want to use a chosen version of Haskell.nix with a
104recent update of Hackage or Stackage. This can be done with JSON pins:
106```bash
107nix-prefetch-git https://github.com/input-output-hk/hackage.nix | tee hackage-src.json
108nix-prefetch-git https://github.com/input-output-hk/stackage.nix | tee stackage-src.json
109```
111The resulting JSON files will correspond to the latest revision of
112[hackage.nix][] and [stackage.nix][]. See
113[Architecture](architecture.md) for more information about how
114these Git repositories correspond to the actual Hackage and Stackage.
116[hackage.nix]: https://github.com/input-output-hk/hackage.nix
117[stackage.nix]: https://github.com/input-output-hk/stackage.nix
119```nix
120{ pkgs ? import <nixpkgs> {} }:
122import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {
123 inherit pkgs;
124 hackageSourceJSON = ./hackage-src.json;
125 stackageSourceJSON = ./stackage-src.json;
127```
129## Using `nix repl`
131It's sometimes useful to load [Haskell.nix][] in the REPL to explore
132attrsets and try examples.
134```
135# example.nix
136{ pkgs ? import <nixpkgs> {} }:
137rec {
138 haskell = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) { inherit pkgs; };
139 pkgNames = pkgs.lib.attrNames haskell.snapshots."lts-13.18";
141```
143Load the example file:
145```
146$ nix repl '<nixpkgs>' example.nix
147Welcome to Nix version 2.3pre6631_e58a7144. Type :? for help.
149Loading '<nixpkgs>'...
150Added 10403 variables.
152Loading 'example2.nix'...
153Added 2 variables.
155nix-repl> lib.take 5 pkgNames
156[ "ALUT" "ANum" "Allure" "Boolean" "BoundedChan" ]
158nix-repl>
159```
161Now that you have `nix-tools` and are able to import [Haskell.nix][],
162you can continue to the next chapter.