pyrox.dev
1---
2title: User's Guide for Haskell in Nixpkgs
3author: Peter Simons
4date: 2015-06-01
5---
6# User's Guide to the Haskell Infrastructure
7
8
9## How to install Haskell packages
10
11Nixpkgs distributes build instructions for all Haskell packages registered on
12[Hackage](http://hackage.haskell.org/), but strangely enough normal Nix package
13lookups don't seem to discover any of them, except for the default version of ghc, cabal-install, and stack:
14```
15$ nix-env -i alex
16error: selector ‘alex’ matches no derivations
17$ nix-env -qa ghc
18ghc-7.10.2
19```
20
21The Haskell package set is not registered in the top-level namespace because it
22is *huge*. If all Haskell packages were visible to these commands, then
23name-based search/install operations would be much slower than they are now. We
24avoided that by keeping all Haskell-related packages in a separate attribute
25set called `haskellPackages`, which the following command will list:
26```
27$ nix-env -f "<nixpkgs>" -qaP -A haskellPackages
28haskellPackages.a50 a50-0.5
29haskellPackages.abacate haskell-abacate-0.0.0.0
30haskellPackages.abcBridge haskell-abcBridge-0.12
31haskellPackages.afv afv-0.1.1
32haskellPackages.alex alex-3.1.4
33haskellPackages.Allure Allure-0.4.101.1
34haskellPackages.alms alms-0.6.7
35[... some 8000 entries omitted ...]
36```
37
38To install any of those packages into your profile, refer to them by their
39attribute path (first column):
40```shell
41nix-env -f "<nixpkgs>" -iA haskellPackages.Allure ...
42```
43
44The attribute path of any Haskell packages corresponds to the name of that
45particular package on Hackage: the package `cabal-install` has the attribute
46`haskellPackages.cabal-install`, and so on. (Actually, this convention causes
47trouble with packages like `3dmodels` and `4Blocks`, because these names are
48invalid identifiers in the Nix language. The issue of how to deal with these
49rare corner cases is currently unresolved.)
50
51Haskell packages whose Nix name (second column) begins with a `haskell-` prefix
52are packages that provide a library whereas packages without that prefix
53provide just executables. Libraries may provide executables too, though: the
54package `haskell-pandoc`, for example, installs both a library and an
55application. You can install and use Haskell executables just like any other
56program in Nixpkgs, but using Haskell libraries for development is a bit
57trickier and we'll address that subject in great detail in section [How to
58create a development environment].
59
60Attribute paths are deterministic inside of Nixpkgs, but the path necessary to
61reach Nixpkgs varies from system to system. We dodged that problem by giving
62`nix-env` an explicit `-f "<nixpkgs>"` parameter, but if you call `nix-env`
63without that flag, then chances are the invocation fails:
64```
65$ nix-env -iA haskellPackages.cabal-install
66error: attribute ‘haskellPackages’ in selection path
67 ‘haskellPackages.cabal-install’ not found
68```
69
70On NixOS, for example, Nixpkgs does *not* exist in the top-level namespace by
71default. To figure out the proper attribute path, it's easiest to query for the
72path of a well-known Nixpkgs package, i.e.:
73```
74$ nix-env -qaP coreutils
75nixos.coreutils coreutils-8.23
76```
77
78If your system responds like that (most NixOS installations will), then the
79attribute path to `haskellPackages` is `nixos.haskellPackages`. Thus, if you
80want to use `nix-env` without giving an explicit `-f` flag, then that's the way
81to do it:
82```shell
83nix-env -qaP -A nixos.haskellPackages
84nix-env -iA nixos.haskellPackages.cabal-install
85```
86
87Our current default compiler is GHC 7.10.x and the `haskellPackages` set
88contains packages built with that particular version. Nixpkgs contains the
89latest major release of every GHC since 6.10.4, however, and there is a whole
90family of package sets available that defines Hackage packages built with each
91of those compilers, too:
92```shell
93nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc6123
94nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc763
95```
96
97The name `haskellPackages` is really just a synonym for
98`haskell.packages.ghc7102`, because we prefer that package set internally and
99recommend it to our users as their default choice, but ultimately you are free
100to compile your Haskell packages with any GHC version you please. The following
101command displays the complete list of available compilers:
102```
103$ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler
104haskell.compiler.ghc6104 ghc-6.10.4
105haskell.compiler.ghc6123 ghc-6.12.3
106haskell.compiler.ghc704 ghc-7.0.4
107haskell.compiler.ghc722 ghc-7.2.2
108haskell.compiler.ghc742 ghc-7.4.2
109haskell.compiler.ghc763 ghc-7.6.3
110haskell.compiler.ghc784 ghc-7.8.4
111haskell.compiler.ghc7102 ghc-7.10.2
112haskell.compiler.ghcHEAD ghc-7.11.20150402
113haskell.compiler.ghcNokinds ghc-nokinds-7.11.20150704
114haskell.compiler.ghcjs ghcjs-0.1.0
115haskell.compiler.jhc jhc-0.8.2
116haskell.compiler.uhc uhc-1.1.9.0
117```
118
119We have no package sets for `jhc` or `uhc` yet, unfortunately, but for every
120version of GHC listed above, there exists a package set based on that compiler.
121Also, the attributes `haskell.compiler.ghcXYC` and
122`haskell.packages.ghcXYC.ghc` are synonymous for the sake of convenience.
123
124## How to create a development environment
125
126### How to install a compiler
127
128A simple development environment consists of a Haskell compiler and one or both
129of the tools `cabal-install` and `stack`. We saw in section
130[How to install Haskell packages] how you can install those programs into your
131user profile:
132```shell
133nix-env -f "<nixpkgs>" -iA haskellPackages.ghc haskellPackages.cabal-install
134```
135
136Instead of the default package set `haskellPackages`, you can also use the more
137precise name `haskell.compiler.ghc7102`, which has the advantage that it refers
138to the same GHC version regardless of what Nixpkgs considers "default" at any
139given time.
140
141Once you've made those tools available in `$PATH`, it's possible to build
142Hackage packages the same way people without access to Nix do it all the time:
143```shell
144cabal get lens-4.11 && cd lens-4.11
145cabal install -j --dependencies-only
146cabal configure
147cabal build
148```
149
150If you enjoy working with Cabal sandboxes, then that's entirely possible too:
151just execute the command
152```shell
153cabal sandbox init
154```
155before installing the required dependencies.
156
157The `nix-shell` utility makes it easy to switch to a different compiler
158version; just enter the Nix shell environment with the command
159```shell
160nix-shell -p haskell.compiler.ghc784
161```
162to bring GHC 7.8.4 into `$PATH`. Alternatively, you can use Stack instead of
163`nix-shell` directly to select compiler versions and other build tools
164per-project. It uses `nix-shell` under the hood when Nix support is turned on.
165See [How to build a Haskell project using Stack].
166
167If you're using `cabal-install`, re-running `cabal configure` inside the spawned
168shell switches your build to use that compiler instead. If you're working on
169a project that doesn't depend on any additional system libraries outside of GHC,
170then it's even sufficient to just run the `cabal configure` command inside of
171the shell:
172```shell
173nix-shell -p haskell.compiler.ghc784 --command "cabal configure"
174```
175
176Afterwards, all other commands like `cabal build` work just fine in any shell
177environment, because the configure phase recorded the absolute paths to all
178required tools like GHC in its build configuration inside of the `dist/`
179directory. Please note, however, that `nix-collect-garbage` can break such an
180environment because the Nix store paths created by `nix-shell` aren't "alive"
181anymore once `nix-shell` has terminated. If you find that your Haskell builds
182no longer work after garbage collection, then you'll have to re-run `cabal
183configure` inside of a new `nix-shell` environment.
184
185### How to install a compiler with libraries
186
187GHC expects to find all installed libraries inside of its own `lib` directory.
188This approach works fine on traditional Unix systems, but it doesn't work for
189Nix, because GHC's store path is immutable once it's built. We cannot install
190additional libraries into that location. As a consequence, our copies of GHC
191don't know any packages except their own core libraries, like `base`,
192`containers`, `Cabal`, etc.
193
194We can register additional libraries to GHC, however, using a special build
195function called `ghcWithPackages`. That function expects one argument: a
196function that maps from an attribute set of Haskell packages to a list of
197packages, which determines the libraries known to that particular version of
198GHC. For example, the Nix expression `ghcWithPackages (pkgs: [pkgs.mtl])`
199generates a copy of GHC that has the `mtl` library registered in addition to
200its normal core packages:
201```
202$ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: [pkgs.mtl])"
203
204[nix-shell:~]$ ghc-pkg list mtl
205/nix/store/zy79...-ghc-7.10.2/lib/ghc-7.10.2/package.conf.d:
206 mtl-2.2.1
207```
208
209This function allows users to define their own development environment by means
210of an override. After adding the following snippet to `~/.config/nixpkgs/config.nix`,
211```nix
212{
213 packageOverrides = super: let self = super.pkgs; in
214 {
215 myHaskellEnv = self.haskell.packages.ghc7102.ghcWithPackages
216 (haskellPackages: with haskellPackages; [
217 # libraries
218 arrows async cgi criterion
219 # tools
220 cabal-install haskintex
221 ]);
222 };
223}
224```
225it's possible to install that compiler with `nix-env -f "<nixpkgs>" -iA
226myHaskellEnv`. If you'd like to switch that development environment to a
227different version of GHC, just replace the `ghc7102` bit in the previous
228definition with the appropriate name. Of course, it's also possible to define
229any number of these development environments! (You can't install two of them
230into the same profile at the same time, though, because that would result in
231file conflicts.)
232
233The generated `ghc` program is a wrapper script that re-directs the real
234GHC executable to use a new `lib` directory --- one that we specifically
235constructed to contain all those packages the user requested:
236```
237$ cat $(type -p ghc)
238#! /nix/store/xlxj...-bash-4.3-p33/bin/bash -e
239export NIX_GHC=/nix/store/19sm...-ghc-7.10.2/bin/ghc
240export NIX_GHCPKG=/nix/store/19sm...-ghc-7.10.2/bin/ghc-pkg
241export NIX_GHC_DOCDIR=/nix/store/19sm...-ghc-7.10.2/share/doc/ghc/html
242export NIX_GHC_LIBDIR=/nix/store/19sm...-ghc-7.10.2/lib/ghc-7.10.2
243exec /nix/store/j50p...-ghc-7.10.2/bin/ghc "-B$NIX_GHC_LIBDIR" "$@"
244```
245
246The variables `$NIX_GHC`, `$NIX_GHCPKG`, etc. point to the *new* store path
247`ghcWithPackages` constructed specifically for this environment. The last line
248of the wrapper script then executes the real `ghc`, but passes the path to the
249new `lib` directory using GHC's `-B` flag.
250
251The purpose of those environment variables is to work around an impurity in the
252popular [ghc-paths](http://hackage.haskell.org/package/ghc-paths) library. That
253library promises to give its users access to GHC's installation paths. Only,
254the library can't possible know that path when it's compiled, because the path
255GHC considers its own is determined only much later, when the user configures
256it through `ghcWithPackages`. So we [patched
257ghc-paths](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/patches/ghc-paths-nix.patch)
258to return the paths found in those environment variables at run-time rather
259than trying to guess them at compile-time.
260
261To make sure that mechanism works properly all the time, we recommend that you
262set those variables to meaningful values in your shell environment, too, i.e.
263by adding the following code to your `~/.bashrc`:
264```bash
265if type >/dev/null 2>&1 -p ghc; then
266 eval "$(egrep ^export "$(type -p ghc)")"
267fi
268```
269
270If you are certain that you'll use only one GHC environment which is located in
271your user profile, then you can use the following code, too, which has the
272advantage that it doesn't contain any paths from the Nix store, i.e. those
273settings always remain valid even if a `nix-env -u` operation updates the GHC
274environment in your profile:
275```bash
276if [ -e ~/.nix-profile/bin/ghc ]; then
277 export NIX_GHC="$HOME/.nix-profile/bin/ghc"
278 export NIX_GHCPKG="$HOME/.nix-profile/bin/ghc-pkg"
279 export NIX_GHC_DOCDIR="$HOME/.nix-profile/share/doc/ghc/html"
280 export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)"
281fi
282```
283
284### How to install a compiler with libraries, hoogle and documentation indexes
285
286If you plan to use your environment for interactive programming, not just
287compiling random Haskell code, you might want to replace `ghcWithPackages` in
288all the listings above with `ghcWithHoogle`.
289
290This environment generator not only produces an environment with GHC and all
291the specified libraries, but also generates a `hoogle` and `haddock` indexes
292for all the packages, and provides a wrapper script around `hoogle` binary that
293uses all those things. A precise name for this thing would be
294"`ghcWithPackagesAndHoogleAndDocumentationIndexes`", which is, regrettably, too
295long and scary.
296
297For example, installing the following environment
298```nix
299{
300 packageOverrides = super: let self = super.pkgs; in
301 {
302 myHaskellEnv = self.haskellPackages.ghcWithHoogle
303 (haskellPackages: with haskellPackages; [
304 # libraries
305 arrows async cgi criterion
306 # tools
307 cabal-install haskintex
308 ]);
309 };
310}
311```
312allows one to browse module documentation index [not too dissimilar to
313this](https://downloads.haskell.org/~ghc/latest/docs/html/libraries/index.html)
314for all the specified packages and their dependencies by directing a browser of
315choice to `~/.nix-profile/share/doc/hoogle/index.html` (or
316`/run/current-system/sw/share/doc/hoogle/index.html` in case you put it in
317`environment.systemPackages` in NixOS).
318
319After you've marveled enough at that try adding the following to your
320`~/.ghc/ghci.conf`
321```
322:def hoogle \s -> return $ ":! hoogle search -cl --count=15 \"" ++ s ++ "\""
323:def doc \s -> return $ ":! hoogle search -cl --info \"" ++ s ++ "\""
324```
325and test it by typing into `ghci`:
326```
327:hoogle a -> a
328:doc a -> a
329```
330
331Be sure to note the links to `haddock` files in the output. With any modern and
332properly configured terminal emulator you can just click those links to
333navigate there.
334
335Finally, you can run
336```shell
337hoogle server --local -p 8080
338```
339and navigate to http://localhost:8080/ for your own local
340[Hoogle](https://www.haskell.org/hoogle/). The `--local` flag makes the hoogle
341server serve files from your nix store over http, without the flag it will use
342`file://` URIs. Note, however, that Firefox and possibly other browsers
343disallow navigation from `http://` to `file://` URIs for security reasons,
344which might be quite an inconvenience. Versions before v5 did not have this
345flag. See
346[this page](http://kb.mozillazine.org/Links_to_local_pages_do_not_work) for
347workarounds.
348
349For NixOS users there's a service which runs this exact command for you.
350Specify the `packages` you want documentation for and the `haskellPackages` set
351you want them to come from. Add the following to `configuration.nix`.
352
353```nix
354services.hoogle = {
355enable = true;
356packages = (hpkgs: with hpkgs; [text cryptonite]);
357haskellPackages = pkgs.haskellPackages;
358};
359```
360
361### How to build a Haskell project using Stack
362
363[Stack](http://haskellstack.org) is a popular build tool for Haskell projects.
364It has first-class support for Nix. Stack can optionally use Nix to
365automatically select the right version of GHC and other build tools to build,
366test and execute apps in an existing project downloaded from somewhere on the
367Internet. Pass the `--nix` flag to any `stack` command to do so, e.g.
368```shell
369git clone --recursive http://github.com/yesodweb/wai
370cd wai
371stack --nix build
372```
373
374If you want `stack` to use Nix by default, you can add a `nix` section to the
375`stack.yaml` file, as explained in the [Stack documentation][stack-nix-doc]. For
376example:
377```yaml
378nix:
379 enable: true
380 packages: [pkgconfig zeromq zlib]
381```
382
383The example configuration snippet above tells Stack to create an ad hoc
384environment for `nix-shell` as in the below section, in which the `pkgconfig`,
385`zeromq` and `zlib` packages from Nixpkgs are available. All `stack` commands
386will implicitly be executed inside this ad hoc environment.
387
388Some projects have more sophisticated needs. For examples, some ad hoc
389environments might need to expose Nixpkgs packages compiled in a certain way, or
390with extra environment variables. In these cases, you'll need a `shell` field
391instead of `packages`:
392```yaml
393nix:
394 enable: true
395 shell-file: shell.nix
396```
397
398For more on how to write a `shell.nix` file see the below section. You'll need
399to express a derivation. Note that Nixpkgs ships with a convenience wrapper
400function around `mkDerivation` called `haskell.lib.buildStackProject` to help you
401create this derivation in exactly the way Stack expects. All of the same inputs
402as `mkDerivation` can be provided. For example, to build a Stack project that
403including packages that link against a version of the R library compiled with
404special options turned on:
405```nix
406with (import <nixpkgs> { });
407
408let R = pkgs.R.override { enableStrictBarrier = true; };
409in
410haskell.lib.buildStackProject {
411 name = "HaskellR";
412 buildInputs = [ R zeromq zlib ];
413}
414```
415
416You can select a particular GHC version to compile with by setting the
417`ghc` attribute as an argument to `buildStackProject`. Better yet, let
418Stack choose what GHC version it wants based on the snapshot specified
419in `stack.yaml` (only works with Stack >= 1.1.3):
420```nix
421{nixpkgs ? import <nixpkgs> { }, ghc ? nixpkgs.ghc}:
422
423with nixpkgs;
424
425let R = pkgs.R.override { enableStrictBarrier = true; };
426in
427haskell.lib.buildStackProject {
428 name = "HaskellR";
429 buildInputs = [ R zeromq zlib ];
430 inherit ghc;
431}
432```
433
434[stack-nix-doc]: http://docs.haskellstack.org/en/stable/nix_integration.html
435
436### How to create ad hoc environments for `nix-shell`
437
438The easiest way to create an ad hoc development environment is to run
439`nix-shell` with the appropriate GHC environment given on the command-line:
440```shell
441nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])"
442```
443
444For more sophisticated use-cases, however, it's more convenient to save the
445desired configuration in a file called `shell.nix` that looks like this:
446```nix
447{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
448let
449 inherit (nixpkgs) pkgs;
450 ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [
451 monad-par mtl
452 ]);
453in
454pkgs.stdenv.mkDerivation {
455 name = "my-haskell-env-0";
456 buildInputs = [ ghc ];
457 shellHook = "eval $(egrep ^export ${ghc}/bin/ghc)";
458}
459```
460
461Now run `nix-shell` --- or even `nix-shell --pure` --- to enter a shell
462environment that has the appropriate compiler in `$PATH`. If you use `--pure`,
463then add all other packages that your development environment needs into the
464`buildInputs` attribute. If you'd like to switch to a different compiler
465version, then pass an appropriate `compiler` argument to the expression, i.e.
466`nix-shell --argstr compiler ghc784`.
467
468If you need such an environment because you'd like to compile a Hackage package
469outside of Nix --- i.e. because you're hacking on the latest version from Git
470---, then the package set provides suitable nix-shell environments for you
471already! Every Haskell package has an `env` attribute that provides a shell
472environment suitable for compiling that particular package. If you'd like to
473hack the `lens` library, for example, then you just have to check out the
474source code and enter the appropriate environment:
475```
476$ cabal get lens-4.11 && cd lens-4.11
477Downloading lens-4.11...
478Unpacking to lens-4.11/
479
480$ nix-shell "<nixpkgs>" -A haskellPackages.lens.env
481[nix-shell:/tmp/lens-4.11]$
482```
483
484At point, you can run `cabal configure`, `cabal build`, and all the other
485development commands. Note that you need `cabal-install` installed in your
486`$PATH` already to use it here --- the `nix-shell` environment does not provide
487it.
488
489## How to create Nix builds for your own private Haskell packages
490
491If your own Haskell packages have build instructions for Cabal, then you can
492convert those automatically into build instructions for Nix using the
493`cabal2nix` utility, which you can install into your profile by running
494`nix-env -i cabal2nix`.
495
496### How to build a stand-alone project
497
498For example, let's assume that you're working on a private project called
499`foo`. To generate a Nix build expression for it, change into the project's
500top-level directory and run the command:
501```shell
502cabal2nix . > foo.nix
503```
504Then write the following snippet into a file called `default.nix`:
505```nix
506{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
507nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { }
508```
509
510Finally, store the following code in a file called `shell.nix`:
511```nix
512{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
513(import ./default.nix { inherit nixpkgs compiler; }).env
514```
515
516At this point, you can run `nix-build` to have Nix compile your project and
517install it into a Nix store path. The local directory will contain a symlink
518called `result` after `nix-build` returns that points into that location. Of
519course, passing the flag `--argstr compiler ghc763` allows switching the build
520to any version of GHC currently supported.
521
522Furthermore, you can call `nix-shell` to enter an interactive development
523environment in which you can use `cabal configure` and `cabal build` to develop
524your code. That environment will automatically contain a proper GHC derivation
525with all the required libraries registered as well as all the system-level
526libraries your package might need.
527
528If your package does not depend on any system-level libraries, then it's
529sufficient to run
530```shell
531nix-shell --command "cabal configure"
532```
533once to set up your build. `cabal-install` determines the absolute paths to all
534resources required for the build and writes them into a config file in the
535`dist/` directory. Once that's done, you can run `cabal build` and any other
536command for that project even outside of the `nix-shell` environment. This
537feature is particularly nice for those of us who like to edit their code with
538an IDE, like Emacs' `haskell-mode`, because it's not necessary to start Emacs
539inside of nix-shell just to make it find out the necessary settings for
540building the project; `cabal-install` has already done that for us.
541
542If you want to do some quick-and-dirty hacking and don't want to bother setting
543up a `default.nix` and `shell.nix` file manually, then you can use the
544`--shell` flag offered by `cabal2nix` to have it generate a stand-alone
545`nix-shell` environment for you. With that feature, running
546```shell
547cabal2nix --shell . > shell.nix
548nix-shell --command "cabal configure"
549```
550is usually enough to set up a build environment for any given Haskell package.
551You can even use that generated file to run `nix-build`, too:
552```shell
553nix-build shell.nix
554```
555
556### How to build projects that depend on each other
557
558If you have multiple private Haskell packages that depend on each other, then
559you'll have to register those packages in the Nixpkgs set to make them visible
560for the dependency resolution performed by `callPackage`. First of all, change
561into each of your projects top-level directories and generate a `default.nix`
562file with `cabal2nix`:
563```shell
564cd ~/src/foo && cabal2nix . > default.nix
565cd ~/src/bar && cabal2nix . > default.nix
566```
567Then edit your `~/.config/nixpkgs/config.nix` file to register those builds in the
568default Haskell package set:
569```nix
570{
571 packageOverrides = super: let self = super.pkgs; in
572 {
573 haskellPackages = super.haskellPackages.override {
574 overrides = self: super: {
575 foo = self.callPackage ../src/foo {};
576 bar = self.callPackage ../src/bar {};
577 };
578 };
579 };
580}
581```
582Once that's accomplished, `nix-env -f "<nixpkgs>" -qA haskellPackages` will
583show your packages like any other package from Hackage, and you can build them
584```shell
585nix-build "<nixpkgs>" -A haskellPackages.foo
586```
587or enter an interactive shell environment suitable for building them:
588```shell
589nix-shell "<nixpkgs>" -A haskellPackages.bar.env
590```
591
592## Miscellaneous Topics
593
594### How to build with profiling enabled
595
596Every Haskell package set takes a function called `overrides` that you can use
597to manipulate the package as much as you please. One useful application of this
598feature is to replace the default `mkDerivation` function with one that enables
599library profiling for all packages. To accomplish that add the following
600snippet to your `~/.config/nixpkgs/config.nix` file:
601```nix
602{
603 packageOverrides = super: let self = super.pkgs; in
604 {
605 profiledHaskellPackages = self.haskellPackages.override {
606 overrides = self: super: {
607 mkDerivation = args: super.mkDerivation (args // {
608 enableLibraryProfiling = true;
609 });
610 };
611 };
612 };
613}
614```
615Then, replace instances of `haskellPackages` in the `cabal2nix`-generated
616`default.nix` or `shell.nix` files with `profiledHaskellPackages`.
617
618### How to override package versions in a compiler-specific package set
619
620Nixpkgs provides the latest version of
621[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
622at the time of this writing. This is fine for users of GHC 7.10.x, but GHC
6237.8.4 cannot compile that binary. Now, one way to solve that problem is to
624register an older version of `ghc-events` in the 7.8.x-specific package set.
625The first step is to generate Nix build instructions with `cabal2nix`:
626```shell
627cabal2nix cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix
628```
629Then add the override in `~/.config/nixpkgs/config.nix`:
630```nix
631{
632 packageOverrides = super: let self = super.pkgs; in
633 {
634 haskell = super.haskell // {
635 packages = super.haskell.packages // {
636 ghc784 = super.haskell.packages.ghc784.override {
637 overrides = self: super: {
638 ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
639 };
640 };
641 };
642 };
643 };
644}
645```
646
647This code is a little crazy, no doubt, but it's necessary because the intuitive
648version
649```nix
650{ # ...
651
652 haskell.packages.ghc784 = super.haskell.packages.ghc784.override {
653 overrides = self: super: {
654 ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
655 };
656 };
657}
658```
659doesn't do what we want it to: that code replaces the `haskell` package set in
660Nixpkgs with one that contains only one entry,`packages`, which contains only
661one entry `ghc784`. This override loses the `haskell.compiler` set, and it
662loses the `haskell.packages.ghcXYZ` sets for all compilers but GHC 7.8.4. To
663avoid that problem, we have to perform the convoluted little dance from above,
664iterating over each step in hierarchy.
665
666Once it's accomplished, however, we can install a variant of `ghc-events`
667that's compiled with GHC 7.8.4:
668```shell
669nix-env -f "<nixpkgs>" -iA haskell.packages.ghc784.ghc-events
670```
671Unfortunately, it turns out that this build fails again while executing the
672test suite! Apparently, the release archive on Hackage is missing some data
673files that the test suite requires, so we cannot run it. We accomplish that by
674re-generating the Nix expression with the `--no-check` flag:
675```shell
676cabal2nix --no-check cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix
677```
678Now the builds succeeds.
679
680Of course, in the concrete example of `ghc-events` this whole exercise is not
681an ideal solution, because `ghc-events` can analyze the output emitted by any
682version of GHC later than 6.12 regardless of the compiler version that was used
683to build the `ghc-events` executable, so strictly speaking there's no reason to
684prefer one built with GHC 7.8.x in the first place. However, for users who
685cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
686older version might be useful.
687
688### How to override packages in all compiler-specific package sets
689
690In the previous section we learned how to override a package in a single
691compiler-specific package set. You may have some overrides defined that you want
692to use across multiple package sets. To accomplish this you could use the
693technique that we learned in the previous section by repeating the overrides for
694all the compiler-specific package sets. For example:
695
696```nix
697{
698 packageOverrides = super: let self = super.pkgs; in
699 {
700 haskell = super.haskell // {
701 packages = super.haskell.packages // {
702 ghc784 = super.haskell.packages.ghc784.override {
703 overrides = self: super: {
704 my-package = ...;
705 my-other-package = ...;
706 };
707 };
708 ghc822 = super.haskell.packages.ghc784.override {
709 overrides = self: super: {
710 my-package = ...;
711 my-other-package = ...;
712 };
713 };
714 ...
715 };
716 };
717 };
718}
719```
720
721However there's a more convenient way to override all compiler-specific package
722sets at once:
723
724```nix
725{
726 packageOverrides = super: let self = super.pkgs; in
727 {
728 haskell = super.haskell // {
729 packageOverrides = self: super: {
730 my-package = ...;
731 my-other-package = ...;
732 };
733 };
734 };
735}
736```
737
738### How to specify source overrides for your Haskell package
739
740When starting a Haskell project you can use `developPackage`
741to define a derivation for your package at the `root` path
742as well as source override versions for Hackage packages, like so:
743
744```nix
745# default.nix
746{ compilerVersion ? "ghc842" }:
747let
748 # pinning nixpkgs using new Nix 2.0 builtin `fetchGit`
749 pkgs = import (fetchGit (import ./version.nix)) { };
750 compiler = pkgs.haskell.packages."${compilerVersion}";
751 pkg = compiler.developPackage {
752 root = ./.;
753 source-overrides = {
754 # Let's say the GHC 8.4.2 haskellPackages uses 1.6.0.0 and your test suite is incompatible with >= 1.6.0.0
755 HUnit = "1.5.0.0";
756 };
757 };
758in pkg
759```
760
761This could be used in place of a simplified `stack.yaml` defining a Nix
762derivation for your Haskell package.
763
764As you can see this allows you to specify only the source version found on
765Hackage and nixpkgs will take care of the rest.
766
767You can also specify `buildInputs` for your Haskell derivation for packages
768that directly depend on external libraries like so:
769
770```nix
771# default.nix
772{ compilerVersion ? "ghc842" }:
773let
774 # pinning nixpkgs using new Nix 2.0 builtin `fetchGit`
775 pkgs = import (fetchGit (import ./version.nix)) { };
776 compiler = pkgs.haskell.packages."${compilerVersion}";
777 pkg = compiler.developPackage {
778 root = ./.;
779 source-overrides = {
780 HUnit = "1.5.0.0"; # Let's say the GHC 8.4.2 haskellPackages uses 1.6.0.0 and your test suite is incompatible with >= 1.6.0.0
781 };
782 };
783 # in case your package source depends on any libraries directly, not just transitively.
784 buildInputs = [ zlib ];
785in pkg.overrideAttrs(attrs: {
786 buildInputs = attrs.buildInputs ++ buildInputs;
787})
788```
789
790Notice that you will need to override (via `overrideAttrs` or similar) the
791derivation returned by the `developPackage` Nix lambda as there is no `buildInputs`
792named argument you can pass directly into the `developPackage` lambda.
793
794### How to recover from GHC's infamous non-deterministic library ID bug
795
796GHC and distributed build farms don't get along well:
797
798 - https://ghc.haskell.org/trac/ghc/ticket/4012
799
800When you see an error like this one
801```
802package foo-0.7.1.0 is broken due to missing package
803text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91
804```
805then you have to download and re-install `foo` and all its dependents from
806scratch:
807```shell
808nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \
809 | xargs -L 1 nix-store --repair-path
810```
811
812If you're using additional Hydra servers other than `hydra.nixos.org`, then it
813might be necessary to purge the local caches that store data from those
814machines to disable these binary channels for the duration of the previous
815command, i.e. by running:
816```shell
817rm ~/.cache/nix/binary-cache*.sqlite
818```
819
820### Builds on Darwin fail with `math.h` not found
821
822Users of GHC on Darwin have occasionally reported that builds fail, because the
823compiler complains about a missing include file:
824```
825fatal error: 'math.h' file not found
826```
827The issue has been discussed at length in [ticket
8286390](https://github.com/NixOS/nixpkgs/issues/6390), and so far no good
829solution has been proposed. As a work-around, users who run into this problem
830can configure the environment variables
831```shell
832export NIX_CFLAGS_COMPILE="-idirafter /usr/include"
833export NIX_CFLAGS_LINK="-L/usr/lib"
834```
835in their `~/.bashrc` file to avoid the compiler error.
836
837### Builds using Stack complain about missing system libraries
838
839```
840-- While building package zlib-0.5.4.2 using:
841 runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...]
842Process exited with code: ExitFailure 1
843Logs have been written to: /home/foo/src/stack-ide/.stack-work/logs/zlib-0.5.4.2.log
844
845Configuring zlib-0.5.4.2...
846Setup.hs: Missing dependency on a foreign library:
847* Missing (or bad) header file: zlib.h
848This problem can usually be solved by installing the system package that
849provides this library (you may need the "-dev" version). If the library is
850already installed but in a non-standard location then you can use the flags
851--extra-include-dirs= and --extra-lib-dirs= to specify where it is.
852If the header file does exist, it may contain errors that are caught by the C
853compiler at the preprocessing stage. In this case you can re-run configure
854with the verbosity flag -v3 to see the error messages.
855```
856
857When you run the build inside of the nix-shell environment, the system
858is configured to find `libz.so` without any special flags -- the compiler
859and linker "just know" how to find it. Consequently, Cabal won't record
860any search paths for `libz.so` in the package description, which means
861that the package works fine inside of nix-shell, but once you leave the
862shell the shared object can no longer be found. That issue is by no
863means specific to Stack: you'll have that problem with any other
864Haskell package that's built inside of nix-shell but run outside of that
865environment.
866
867You can remedy this issue in several ways. The easiest is to add a `nix` section
868to the `stack.yaml` like the following:
869```yaml
870nix:
871 enable: true
872 packages: [ zlib ]
873```
874
875Stack's Nix support knows to add `${zlib.out}/lib` and `${zlib.dev}/include`
876as an `--extra-lib-dirs` and `extra-include-dirs`, respectively.
877Alternatively, you can achieve the same effect by hand. First of all, run
878```
879$ nix-build --no-out-link "<nixpkgs>" -A zlib
880/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8
881```
882to find out the store path of the system's zlib library. Now, you can
883
884 1. add that path (plus a "/lib" suffix) to your `$LD_LIBRARY_PATH`
885 environment variable to make sure your system linker finds `libz.so`
886 automatically. It's no pretty solution, but it will work.
887
888 2. As a variant of (1), you can also install any number of system
889 libraries into your user's profile (or some other profile) and point
890 `$LD_LIBRARY_PATH` to that profile instead, so that you don't have to
891 list dozens of those store paths all over the place.
892
893 3. The solution I prefer is to call stack with an appropriate
894 --extra-lib-dirs flag like so:
895 ```shell
896 stack --extra-lib-dirs=/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8/lib build
897 ```
898
899Typically, you'll need `--extra-include-dirs` as well. It's possible
900to add those flag to the project's `stack.yaml` or your user's
901global `~/.stack/global/stack.yaml` file so that you don't have to
902specify them manually every time. But again, you're likely better off
903using Stack's Nix support instead.
904
905The same thing applies to `cabal configure`, of course, if you're
906building with `cabal-install` instead of Stack.
907
908### Creating statically linked binaries
909
910There are two levels of static linking. The first option is to configure the
911build with the Cabal flag `--disable-executable-dynamic`. In Nix expressions,
912this can be achieved by setting the attribute:
913```
914enableSharedExecutables = false;
915```
916That gives you a binary with statically linked Haskell libraries and
917dynamically linked system libraries.
918
919To link both Haskell libraries and system libraries statically, the additional
920flags `--ghc-option=-optl=-static --ghc-option=-optl=-pthread` need to be used.
921In Nix, this is accomplished with:
922```
923configureFlags = [ "--ghc-option=-optl=-static" "--ghc-option=-optl=-pthread" ];
924```
925
926It's important to realize, however, that most system libraries in Nix are
927built as shared libraries only, i.e. there is just no static library
928available that Cabal could link!
929
930### Building GHC with integer-simple
931
932By default GHC implements the Integer type using the
933[GNU Multiple Precision Arithmetic (GMP) library](https://gmplib.org/).
934The implementation can be found in the
935[integer-gmp](http://hackage.haskell.org/package/integer-gmp) package.
936
937A potential problem with this is that GMP is licensed under the
938[GNU Lesser General Public License (LGPL)](http://www.gnu.org/copyleft/lesser.html),
939a kind of "copyleft" license. According to the terms of the LGPL, paragraph 5,
940you may distribute a program that is designed to be compiled and dynamically
941linked with the library under the terms of your choice (i.e., commercially) but
942if your program incorporates portions of the library, if it is linked
943statically, then your program is a "derivative"--a "work based on the
944library"--and according to paragraph 2, section c, you "must cause the whole of
945the work to be licensed" under the terms of the LGPL (including for free).
946
947The LGPL licensing for GMP is a problem for the overall licensing of binary
948programs compiled with GHC because most distributions (and builds) of GHC use
949static libraries. (Dynamic libraries are currently distributed only for macOS.)
950The LGPL licensing situation may be worse: even though
951[The Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license)
952is essentially a "free software" license (BSD3), according to
953paragraph 2 of the LGPL, GHC must be distributed under the terms of the LGPL!
954
955To work around these problems GHC can be build with a slower but LGPL-free
956alternative implemention for Integer called
957[integer-simple](http://hackage.haskell.org/package/integer-simple).
958
959To get a GHC compiler build with `integer-simple` instead of `integer-gmp` use
960the attribute: `haskell.compiler.integer-simple."${ghcVersion}"`.
961For example:
962```
963$ nix-build -E '(import <nixpkgs> {}).haskell.compiler.integer-simple.ghc802'
964...
965$ result/bin/ghc-pkg list | grep integer
966 integer-simple-0.1.1.1
967```
968The following command displays the complete list of GHC compilers build with `integer-simple`:
969```
970$ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler.integer-simple
971haskell.compiler.integer-simple.ghc7102 ghc-7.10.2
972haskell.compiler.integer-simple.ghc7103 ghc-7.10.3
973haskell.compiler.integer-simple.ghc722 ghc-7.2.2
974haskell.compiler.integer-simple.ghc742 ghc-7.4.2
975haskell.compiler.integer-simple.ghc783 ghc-7.8.3
976haskell.compiler.integer-simple.ghc784 ghc-7.8.4
977haskell.compiler.integer-simple.ghc801 ghc-8.0.1
978haskell.compiler.integer-simple.ghc802 ghc-8.0.2
979haskell.compiler.integer-simple.ghcHEAD ghc-8.1.20170106
980```
981
982To get a package set supporting `integer-simple` use the attribute:
983`haskell.packages.integer-simple."${ghcVersion}"`. For example
984use the following to get the `scientific` package build with `integer-simple`:
985```shell
986nix-build -A haskell.packages.integer-simple.ghc802.scientific
987```
988
989### Quality assurance
990
991The `haskell.lib` library includes a number of functions for checking for
992various imperfections in Haskell packages. It's useful to apply these functions
993to your own Haskell packages and integrate that in a Continuous Integration
994server like [hydra](https://nixos.org/hydra/) to assure your packages maintain a
995minimum level of quality. This section discusses some of these functions.
996
997#### failOnAllWarnings
998
999Applying `haskell.lib.failOnAllWarnings` to a Haskell package enables the
1000`-Wall` and `-Werror` GHC options to turn all warnings into build failures.
1001
1002#### buildStrictly
1003
1004Applying `haskell.lib.buildStrictly` to a Haskell package calls
1005`failOnAllWarnings` on the given package to turn all warnings into build
1006failures. Additionally the source of your package is gotten from first invoking
1007`cabal sdist` to ensure all needed files are listed in the Cabal file.
1008
1009#### checkUnusedPackages
1010
1011Applying `haskell.lib.checkUnusedPackages` to a Haskell package invokes
1012the [packunused](http://hackage.haskell.org/package/packunused) tool on the
1013package. `packunused` complains when it finds packages listed as build-depends
1014in the Cabal file which are redundant. For example:
1015
1016```
1017$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.haskell.lib.checkUnusedPackages {} pkgs.haskellPackages.scientific'
1018these derivations will be built:
1019 /nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv
1020...
1021detected package components
1022~~~~~~~~~~~~~~~~~~~~~~~~~~~
1023
1024 - library
1025 - testsuite(s): test-scientific
1026 - benchmark(s): bench-scientific*
1027
1028(component names suffixed with '*' are not configured to be built)
1029
1030library
1031~~~~~~~
1032
1033The following package dependencies seem redundant:
1034
1035 - ghc-prim-0.5.0.0
1036
1037testsuite(test-scientific)
1038~~~~~~~~~~~~~~~~~~~~~~~~~~
1039
1040no redundant packages dependencies found
1041
1042builder for ‘/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv’ failed with exit code 1
1043error: build of ‘/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv’ failed
1044```
1045
1046As you can see, `packunused` finds out that although the testsuite component has
1047no redundant dependencies the library component of `scientific-0.3.5.1` depends
1048on `ghc-prim` which is unused in the library.
1049
1050### Using hackage2nix with nixpkgs
1051
1052Hackage package derivations are found in the
1053[`hackage-packages.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/hackage-packages.nix)
1054file within `nixpkgs` and are used as the initial package set for
1055`haskellPackages`. The `hackage-packages.nix` file is not meant to be edited
1056by hand, but rather autogenerated by [`hackage2nix`](https://github.com/NixOS/cabal2nix/tree/master/hackage2nix),
1057which by default uses the [`configuration-hackage2nix.yaml`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/configuration-hackage2nix.yaml)
1058file to generate all the derivations.
1059
1060To modify the contents `configuration-hackage2nix.yaml`, follow the
1061instructions on [`hackage2nix`](https://github.com/NixOS/cabal2nix/tree/master/hackage2nix).
1062
1063## Other resources
1064
1065 - The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
1066 provides an introduction into Haskell NG aimed at beginners. The slides are
1067 available at http://cryp.to/nixos-meetup-3-slides.pdf and also -- in a form
1068 ready for cut & paste -- at
1069 https://github.com/NixOS/cabal2nix/blob/master/doc/nixos-meetup-3-slides.md.
1070
1071 - Another Youtube video is [Escaping Cabal Hell with Nix](https://www.youtube.com/watch?v=mQd3s57n_2Y),
1072 which discusses the subject of Haskell development with Nix but also provides
1073 a basic introduction to Nix as well, i.e. it's suitable for viewers with
1074 almost no prior Nix experience.
1075
1076 - Oliver Charles wrote a very nice [Tutorial how to develop Haskell packages with Nix](http://wiki.ocharles.org.uk/Nix).
1077
1078 - The *Journey into the Haskell NG infrastructure* series of postings
1079 describe the new Haskell infrastructure in great detail:
1080
1081 - [Part 1](https://nixos.org/nix-dev/2015-January/015591.html)
1082 explains the differences between the old and the new code and gives
1083 instructions how to migrate to the new setup.
1084
1085 - [Part 2](https://nixos.org/nix-dev/2015-January/015608.html)
1086 looks in-depth at how to tweak and configure your setup by means of
1087 overrides.
1088
1089 - [Part 3](https://nixos.org/nix-dev/2015-April/016912.html)
1090 describes the infrastructure that keeps the Haskell package set in Nixpkgs
1091 up-to-date.