@@ -1,310 +0,0 @@
1−# User Guide
2−
3−[Haskell.nix][] can be use for two different use cases:
4−
5−### Use 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 <nixpkgs> (import ./. {}).nixpkgsArgs; haskell-nix.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 <nixpkgs> (import ./. {}).nixpkgsArgs; (haskell-nix.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 <nixpkgs> (import ./. {}).nixpkgsArgs; (haskell-nix.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−### Use 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`.
38−
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
46−
47−## Installing `nix-tools`
48−
49−To build the latest `nix-tools` and store the result at `./nt`, run:
50−
51−```bash
52−nix build -f https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz pkgs.haskell-nix.nix-tools --out-link nt
53−```
54−
55−If you would like to then install `nix-tools` into your profile, run:
56−
57−```bash
58−nix-env -i ./nt
59−```
60−
61−## Getting the [Haskell.nix][] source (optional)
62−
63−The [Haskell.nix][] and `nix-tools` source will be useful if you would
64−like to contribute improvements, or read the source code to fully
65−understand something that the documentation doesn't cover.
66−
67−```bash
68−git clone https://github.com/input-output-hk/nix-tools
69−git clone https://github.com/input-output-hk/haskell.nix
70−cd haskell.nix
71−nix build -f . pkgs.haskell-nix.nix-tools --arg sourcesOverride '{ nix-tools = ../nix-tools; }' --out-link nt
72−```
73−
74−## Setting up the Cachix binary cache
75−
76−CI pushes to [cachix](https://cachix.org) so you can benefit from the cache if
77−you pin a combination of `haskell.nix` and `nixpkgs` built by CI. You'll need
78−to configure the [iohk cachix](https://iohk.cachix.org) as a
79−`substituter` for `nix` and add the public key found at the url to
80−`trusted-public-keys`.
81−
82−## Using [Haskell.nix][] with your project
83−
84−The easiest way to get a hold of [Haskell.nix][] is with
85−[`fetchTarball`](https://nixos.org/nix/manual/#ssec-builtins).
86−
87−```nix
88−import <nixpkgs> (import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}).nixpkgsArgs
89−```
90−
91−### Using your cabal.project file
92−
93−If your project has a `cabal.project` you can add a `default.nix` like this:
94−
95−```nix
96−{ pkgs ? import <nixpkgs> (import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}).nixpkgsArgs
97−, compiler-nix-name ? "ghc865"
98−}:
99− pkgs.haskell-nix.cabalProject {
100− src = pkgs.haskell-nix.haskellLib.cleanGit { src = ./.; };
101− inherit compiler-nix-name;
102− # pkg-def-extras = [
103− # # Additional packages ontop of all those listed in `cabal.project`
104− # ];
105− # modules = [{
106− # # Specific package overrides would go here for example:
107− # packages.cbors.package.ghcOptions = "-Werror";
108− # packages.cbors.patches = [ ./one.patch ];
109− # packages.cbors.flags.optimize-gmp = false;
110− # # It may be better to set flags in `cabal.project` instead
111− # # (`plan-to-nix` will include them as defaults).
112− # }];
113− }
114−```
115−
116−Note: The `cleanGit` call will exclude any files not in the index file
117−in the local `.git` directory. This is extremely useful as it avoids
118−unwanted builds (for instance when the contents of `dist-newstyle` are
119−modified by cabal). It is important that `src` is the root directory
120−of the repo (so `cleanGit` can find the `.git` directory). If the project
121−is not at the root of the repo, then also pass `subDir` to `cleanGit` with the
122−location of the project relative to `src` as a string ([more information
123−on using cleanGit](clean-git.md)). For example:
124−
125−```
126− src = pkgs.haskell-nix.haskellLib.cleanGit
127− { src = ./.; subDir = "subdir/another-subdir"; };
128−```
129−
130−If you want to use a custom filtering function, don't use the built-in nix `filterSource` function.
131−Due to some technicalities about how filtering and the nix store work, it will cause all components in
132−your project to be rebuilt any time any part of the project source changes. Use `cleanSourceWith` instead:
133−
134−```
135− src = pkgs.haskell-nix.haskellLib.cleanSourceWith
136− { src = ./.; filter = myFilterFunction; };
137−```
138−
139−Note that `cleanSourceWith` will also take the `subDir` argument.
140−
141−You can build a component from your project with `nix-build` (in this
142−case the `hello` executable in a `helloworld` package):
143−
144−```bash
145−nix-build -A helloworld.components.exes.hello
146−```
147−
148−For interactive development you can run:
149−
150−```bash
151−nix-shell -A shellFor
152−```
153−
154−The resulting shell will include all the dependencies of the local packages
155−listed in your `cabal.project` file (but it will not build those local
156−packages).
157−
158−Inside the shell use `cabal new-build` and `cabal new-repl` to work on the
159−cabal project as you normally would. They will use the packages provided
160−by nix whenever possible.
161−
162−It is a good idea to add `write-ghc-environment-files: never` to your
163−`cabal.project` file to prevent unwanted `.ghc.environment.*` files
164−(they will prevent subsequent `nix-shell` invocations from working
165−properly).
166−
167−Adding an `index-state` to your `cabal.project` can pin the plan used so that
168−the same packages will be built each time (until you change the index-state
169−or one of the constraints in your local `.cabal` files).
170−
171−### Using your stack.yaml file
172−
173−If your project has a `stack.yaml` you can add a `default.nix` like this:
174−
175−```nix
176−{ pkgs ? import <nixpkgs> (import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}).nixpkgsArgs
177−}:
178− pkgs.haskell-nix.stackProject {
179− src = pkgs.haskell-nix.haskellLib.cleanGit { src = ./.; };
180− # pkg-def-extras = [
181− # # Additional packages ontop of all those listed in `stack.yaml`
182− # ];
183− # modules = [
184− # # Specific package overrides would go here for example:
185− # packages.cbors.package.ghcOptions = "-Werror";
186− # packages.cbors.patches = [ ./one.patch ];
187− # packages.cbors.flags.optimize-gmp = false;
188− # # It may be better to set flags in `stack.yaml` instead
189− # # (`stack-to-nix` will include them as defaults).
190− # ];
191− }
192−```
193−
194−You can build a component from your project with `nix-build` (in this
195−case the `hello` executable in a `helloworld` package):
196−
197−```bash
198−nix-build -A helloworld.components.exes.hello
199−```
200−
201−### Pinning the [Haskell.nix][] version
202−
203−For simplicity's sake we will use `fetchTarball` for the examples in
204−this documentation. This will always get the latest version, and is
205−similar to an auto-updating Nix channel.
206−
207−However, in your own project, you may wish to pin [Haskell.nix][] (as
208−you would pin Nixpkgs). This will make your builds reproducable, more
209−predictable, and faster (because the fixed version is cached).
210−
211−One way of doing this is to use `nix-prefetch-git` to get a JSON file
212−with a revision and SHA-256 hash of [Haskell.nix][].
213−
214−```
215−$ nix-prefetch-git --quiet https://github.com/input-output-hk/haskell.nix | tee haskell-nix-src.json
216−{
217− "url": "https://github.com/input-output-hk/haskell.nix",
218− "rev": "f1a94a4c82a2ab999a67c3b84269da78d89f0075",
219− "date": "2019-06-05T01:06:12+00:00",
220− "sha256": "0ggxsppjlb6q6a83y12cwgrdnqnw1s128rpibgzs5p1966bdfqla",
221− "fetchSubmodules": false
222−}
223−```
224−
225−(The `tee` command is just to show you the result.)
226−Use the following expression to import that version:
227−
228−```nix
229−{ nixpkgs ? <nixpkgs> }:
230−
231−let
232− spec = builtins.fromJSON (builtins.readFile ./haskell-nix-src.json);
233− haskell-nix-src = (import nixpkgs {}).fetchgit {
234− name = "haskell-lib";
235− inherit (spec) url rev sha256 fetchSubmodules;
236− };
237−in
238− import nixpkgs (import haskell-nix-src)
239−```
240−
241−There are other possible schemes for pinning. See
242−[`haskell.nix/lib/fetch-external.nix`](https://github.com/input-output-hk/haskell.nix/blob/master/lib/fetch-external.nix),
243−the [niv](https://github.com/nmattia/niv) tool, or the Nix Flakes
244−proposal.
245−
246−### Overriding the Hackage version
247−
248−Sometimes you might want to use a chosen version of Haskell.nix with a
249−recent update of Hackage or Stackage. This can be done with JSON pins:
250−
251−```bash
252−nix-prefetch-git https://github.com/input-output-hk/hackage.nix | tee hackage-src.json
253−nix-prefetch-git https://github.com/input-output-hk/stackage.nix | tee stackage-src.json
254−```
255−
256−The resulting JSON files will correspond to the latest revision of
257−[hackage.nix][] and [stackage.nix][]. See
258−[Architecture](architecture.md) for more information about how
259−these Git repositories correspond to the actual Hackage and Stackage.
260−
261−[hackage.nix]: https://github.com/input-output-hk/hackage.nix
262−[stackage.nix]: https://github.com/input-output-hk/stackage.nix
263−
264−```nix
265−{ pkgs ? import <nixpkgs> (haskellNixArgs // { overlays = haskellNixArgs.overlays ++ [
266− (self: super: {
267− haskell-nix = super.haskell-nix // {
268− hackageSourceJSON = ./hackage-src.json;
269− stackageSourceJSON = ./stackage-src.json;
270− };
271− })]; })
272−, haskellNixArgs ? (import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}).nixpkgsArgs
273−}:
274− pkgs
275−```
276−
277−## Using `nix repl`
278−
279−It's sometimes useful to load [Haskell.nix][] in the REPL to explore
280−attrsets and try examples.
281−
282−```
283−# example.nix
284−{ nixpkgs ? <nixpkgs> }:
285−rec {
286− haskell = import nixpkgs (import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}).nixpkgsArgs;
287− pkgNames = haskell.pkgs.lib.attrNames haskell.haskell-nix.snapshots."lts-13.18";
288−}
289−```
290−
291−Load the example file:
292−
293−```
294−$ nix repl '<nixpkgs>' example.nix
295−Welcome to Nix version 2.3pre6631_e58a7144. Type :? for help.
296−
297−Loading '<nixpkgs>'...
298−Added 10403 variables.
299−
300−Loading 'example2.nix'...
301−Added 2 variables.
302−
303−nix-repl> lib.take 5 pkgNames
304−[ "ALUT" "ANum" "Allure" "Boolean" "BoundedChan" ]
305−
306−nix-repl>
307−```
308−
309−Now that you have `nix-tools` and are able to import [Haskell.nix][],
310−you can continue to the next chapter.