@@ -35,6 +35,33 @@ nix.binaryCaches = [
3535
3636This can be tricky to get setup properly. If you're still having trouble getting cache hits, consult the corresponding [troubleshooting section](../../troubleshooting#why-am-i-building-ghc).
3737
38+## Niv
39+
40+[Niv](https://github.com/nmattia/niv) is a command line tool for keeping tack of Nix project dependencies.
41+
42+This guide assumes that the `sources.haskellNix` will be set to point
43+a pinned copy of the haskell.nix github repo. One easy way to do this
44+is to use Niv. If you prefer not to use Niv another option is described
45+in the in the "Using haskell.nix without niv" section of this document.
46+
47+If you want to use Nix Flakes to pin your dependencies then you should
48+consider following the [Getting started with flakes](./getting-started-flakes.md)
49+document instead of this one.
50+
51+After installing niv you can initialize niv and pin the latest haskell.nix
52+commit by running the following in the root directory of the project:
53+
54+```
55+niv init
56+niv add input-output-hk/haskell.nix -n haskellNix
57+```
58+
59+Then when you want to update to the latest version of haskellNix use:
60+
61+```
62+niv update haskellNix
63+```
64+
3865## Scaffolding
3966
4067The following work with `stack.yaml` and `cabal.project` based
@@ -43,21 +70,28 @@ projects.
4370Add `default.nix`:
4471
4572```nix
46−{ # Fetch the latest haskell.nix and import its default.nix
47− haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}
48−
49−# haskell.nix provides access to the nixpkgs pins which are used by our CI,
50−# hence you will be more likely to get cache hits when using these.
51−# But you can also just use your own, e.g. '<nixpkgs>'.
52−, nixpkgsSrc ? haskellNix.sources.nixpkgs-2009
53−
54−# haskell.nix provides some arguments to be passed to nixpkgs, including some
55−# patches and also the haskell.nix functionality itself as an overlay.
56−, nixpkgsArgs ? haskellNix.nixpkgsArgs
57−
58−# import nixpkgs with overlays
59−, pkgs ? import nixpkgsSrc nixpkgsArgs
60−}: pkgs.haskell-nix.project {
73+let
74+ # Read in the Niv sources
75+ sources = import ./nix/sources.nix {};
76+ # If ./nix/sources.nix file is not found run:
77+ # niv init
78+ # niv add input-output-hk/haskell.nix -n haskellNix
79+
80+ # Fetch the haskell.nix commit we have pinned with Niv
81+ haskellNix = import sources.haskellNix {};
82+ # If haskellNix is not found run:
83+ # niv add input-output-hk/haskell.nix -n haskellNix
84+
85+ # Import nixpkgs and pass the haskell.nix provided nixpkgsArgs
86+ pkgs = import
87+ # haskell.nix provides access to the nixpkgs pins which are used by our CI,
88+ # hence you will be more likely to get cache hits when using these.
89+ # But you can also just use your own, e.g. '<nixpkgs>'.
90+ haskellNix.sources.nixpkgs-2009
91+ # These arguments passed to nixpkgs, include some patches and also
92+ # the haskell.nix functionality itself as an overlay.
93+ haskellNix.nixpkgsArgs;
94+in pkgs.haskell-nix.project {
6195 # 'cleanGit' cleans a source directory based on the files known by git
6296 src = pkgs.haskell-nix.haskellLib.cleanGit {
6397 name = "haskell-nix-project";
@@ -96,20 +130,40 @@ nix-build -A projectCross.ghcjs.hsPkgs.your-package-name.components.exes.your-ex
96130nix-build -A projectCross.mingwW64.hsPkgs.your-package-name.components.exes.your-exe-name
97131```
98132
99−To open a shell for use with `cabal` run:
133+To open a shell for use with `cabal`, `hlint` and `haskell-language-server` add `shell.nix`:
134+
135+```nix
136+(import ./default.nix).shellFor {
137+ tools = {
138+ cabal = "3.2.0.0";
139+ hlint = "latest";
140+ haskell-language-server = "latest";
141+ };
142+}
143+```
144+
145+Then run:
100146
101147```shell
102−nix-shell -A shellFor
148+nix-shell
103149cabal new-repl your-package-name:library:your-package-name
104150cabal new-build your-package-name
105151```
106152
107153To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
108154
109−### Pinning the [haskell.nix][] version
155+## Using haskell.nix without Niv
110156
111−For simplicity's sake we will use `fetchTarball` for the examples in
112−this documentation. This will always get the latest version, and is
157+If you would prefer not to use niv you can replace
158+`sources = import ./nix/sources.nix {};` in the examples with:
159+
160+```nix
161+let sources = {
162+ haskellNix = builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz";
163+ };
164+```
165+
166+The `fetchTarball` call above will always get the latest version, and is
113167similar to an auto-updating Nix channel.
114168
115169However, in your own project, you may wish to pin [haskell.nix][] (as
@@ -119,10 +173,9 @@ predictable, and faster (because the fixed version is cached).
119173Straightforward way of doing this is to change the branch name to a revision.
120174
121175```nix
122−{ # Fetch a specific haskell.nix and import its default.nix
123− haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}
124−
125−...
176+let sources = {
177+ haskellNix = import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {};
178+ };
126179```
127180
128181There are other possible schemes for pinning. See