git.iko.soy/haskell.nix
on c773606 help sign in
haskell.nix/docs/tutorials/development.md
217 lines 7.0 kB history raw
1Haskell.nix also provides reproducible development environments for
2your Haskell projects. These environments can contain not only GHC and
3your Haskell package dependencies, but also the required system
4libraries and build tools.
6Inside the development shell, you can run commands such as `ghc`,
7`ghci`, or `cabal new‑build` (`cabal build` on Cabal 3.0),
8and they will have all dependencies available.
10Every dependency will be cached in your Nix store. If you have set up
11Hydra CI, then your team can share pre-built dependencies.
13These examples assume that you have created your package set as
14described in [Creating Nix builds for your projects](getting-started.md) and
15it exists in a file called `default.nix`.
17!!! note
19 Old-style `cabal build` and `stack` builds are not (yet)
20 supported. For example, `stack` will (by design) download and
21 rebuild all dependencies, even though they are available in the
22 shell. However, if you have a Stack project, you can generate the
23 package set with Haskell.nix, then use `cabal new‑build` to work
24 on it. Starting Cabal 3.0 `cabal build` will work out of the box, as
25 new style builds are the default.
27## How to get a development shell for a package
29Run a `nix‑shell` on `components.all` of your package. `all` is a
30synthetic component whose dependencies are the union of the
31dependencies of all components in the package. Therefore, you will be
32able to build the test suites because their dependencies will be
33included.
35```nix
36# shell.nix
37let
38 hsPkgs = import ./default.nix {};
39in
40 hsPkgs.my-package.components.all
41```
43## How to get a development shell for a multi-package project
45If you have a Cabal or Stack project with multiple packages
46(i.e. multiple `.cabal` files, not a single package with multiple
47components), then you will need a development environment that
48contains the _dependencies_ of your packages, but not the packages
49themselves. This is what the [`shellFor`][shellFor] function does.
51```nix
52# shell.nix
53{ pkgs ? import <nixpkgs> {} }:
55let
56 hsPkgs = import ./default.nix { inherit pkgs; };
57in
58 hsPkgs.shellFor {
59 # Include only the *local* packages of your project.
60 packages = ps: with ps; [
61 pkga
62 pkgb
63 ];
65 # Builds a Hoogle documentation index of all dependencies,
66 # and provides a "hoogle" command to search the index.
67 withHoogle = true;
69 # You might want some extra tools in the shell (optional).
71 # Some common tools can be added with the `tools` argument
72 tools = { cabal = "3.2.0.0"; hlint = "2.2.11"; };
73 # See overlays/tools.nix for more details
75 # Some you may need to get some other way.
76 buildInputs = with pkgs.haskellPackages;
77 [ ghcid ];
79 # Prevents cabal from choosing alternate plans, so that
80 # *all* dependencies are provided by Nix.
81 exactDeps = true;
82 }
83```
85See also: [Haskell.nix Library Reference: `shellFor`][shellFor]
87[shellFor]: ../reference/library.md#shellfor
89## How to get a local Hoogle index
91If you need a local Hoogle for all the dependencies of your project create this file
93```nix
94# shell-hoogle.nix
95let
96 hsPkgs = import ./default.nix {};
97in
98 hsPkgs.shellFor {
99 packages = ps: [ps.my-package];
100 withHoogle = true;
101 }
102```
104and run `nix-shell shell-hoogle.nix --run "hoogle server --local"`.
105This will open a local Hoogle server at `http://127.0.0.1:8080`.
108## How to get an ad-hoc development shell including certain packages
110This creates a development environment with the given packages
111registered in the package database. The `ghcWithPackages` function
112operates on a Haskell.nix package set, and accepts an argument that
113selects packages from the larger package set.
115```nix
116# shell.nix
117let
118 haskellNix = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {};
119 nixpkgs = import haskellNix.sources.nixpkgs-1909 haskellNix.nixpkgsArgs;
120 haskell = nixpkgs.haskell-nix;
121in
122 haskell.haskellPackages.ghcWithPackages (ps: with ps;
123 [ lens conduit conduit-extra ])
124```
126If you need a Hoogle documentation index, use `ghcWithHoogle` in place
127of `ghcWithPackages`.
129## How to get packages from a certain Stackage snapshot
131Haskell.nix knows about every released Stackage snapshot. You can use
132it to build packages from a given snapshot, without setting up a full
133project.
135```nix
136let
137 haskellNix = import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {};
138 nixpkgs = import haskellNix.sources.nixpkgs-1909 haskellNix.nixpkgsArgs;
139 haskell = nixpkgs.haskell-nix;
140in
141 haskell.snapshots."lts-13.18".alex.components.exes.alex
142```
144There are Haskell.nix package sets for every Stackage snaphot under
145`haskell.snapshots`.
147The alias `haskell.haskellPackages` corresponds to the package set for
148a recent LTS Haskell version.
150You can use `ghcWithPackages` on any of these package sets to quickly
151get a shell with some packages.
153!!! warning
154 The build will not work if your Nixpkgs does not contain the version
155 of GHC specified in the snapshot. Nixpkgs only carries the
156 latest version of each recent release series, so many snapshots
157 can't be built.
160## Emacs IDE support
162Once you have a development shell, then you can begin configuring
163Emacs to use it. The way I do it is:
1651. Run [lorri watch](https://github.com/target/lorri) to continously
166 build the shell environment and maintain GC roots.
1682. Use [emacs‑direnv](https://github.com/wbolster/emacs-direnv) to
169 push the development environment into Emacs.
1713. Use [Dante](https://github.com/jyp/dante) for highlighting errors
172 and auto-completion. You must customize Dante to prevent it from
173 automatically using `nix‑shell` or `stack`. Trim `dante‑methods` to
174 just `new‑build` and `bare‑ghci`.
176 You can also use [`.dir‑locals.el`](https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html)
177 for this. If your project has multiple targets, set `dante‑target`
178 per-directory.
1804. For [`haskell‑mode`](https://github.com/haskell/haskell-mode)
181 interactive Haskell, set `haskell‑process‑type` to
182 `cabal‑new‑repl`.
184## Using `nix repl`
186It's sometimes useful to load [Haskell.nix][] in the REPL to explore
187attrsets and try examples.
189```
190# example.nix
191{ nixpkgs ? <nixpkgs> }:
192rec {
193 haskell = import nixpkgs (import (builtins.fetchTarball https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz) {}).nixpkgsArgs;
194 pkgNames = haskell.pkgs.lib.attrNames haskell.haskell-nix.snapshots."lts-13.18";
196```
198Load the example file:
200```
201$ nix repl '<nixpkgs>' example.nix
202Welcome to Nix version 2.3pre6631_e58a7144. Type :? for help.
204Loading '<nixpkgs>'...
205Added 10403 variables.
207Loading 'example.nix'...
208Added 2 variables.
210nix-repl> lib.take 5 pkgNames
211[ "ALUT" "ANum" "Allure" "Boolean" "BoundedChan" ]
213nix-repl>
214```
216Now that you have `nix-tools` and are able to import [Haskell.nix][],
217you can continue to the next chapter.