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-profiles/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 -p 8080 --local
338```
339and navigate to http://localhost:8080/ for your own local
340[Hoogle](https://www.haskell.org/hoogle/).
341
342### How to build a Haskell project using Stack
343
344[Stack](http://haskellstack.org) is a popular build tool for Haskell projects.
345It has first-class support for Nix. Stack can optionally use Nix to
346automatically select the right version of GHC and other build tools to build,
347test and execute apps in an existing project downloaded from somewhere on the
348Internet. Pass the `--nix` flag to any `stack` command to do so, e.g.
349```shell
350git clone --recursive http://github.com/yesodweb/wai
351cd wai
352stack --nix build
353```
354
355If you want `stack` to use Nix by default, you can add a `nix` section to the
356`stack.yaml` file, as explained in the [Stack documentation][stack-nix-doc]. For
357example:
358```yaml
359nix:
360 enable: true
361 packages: [pkgconfig zeromq zlib]
362```
363
364The example configuration snippet above tells Stack to create an ad hoc
365environment for `nix-shell` as in the below section, in which the `pkgconfig`,
366`zeromq` and `zlib` packages from Nixpkgs are available. All `stack` commands
367will implicitly be executed inside this ad hoc environment.
368
369Some projects have more sophisticated needs. For examples, some ad hoc
370environments might need to expose Nixpkgs packages compiled in a certain way, or
371with extra environment variables. In these cases, you'll need a `shell` field
372instead of `packages`:
373```yaml
374nix:
375 enable: true
376 shell-file: shell.nix
377```
378
379For more on how to write a `shell.nix` file see the below section. You'll need
380to express a derivation. Note that Nixpkgs ships with a convenience wrapper
381function around `mkDerivation` called `haskell.lib.buildStackProject` to help you
382create this derivation in exactly the way Stack expects. All of the same inputs
383as `mkDerivation` can be provided. For example, to build a Stack project that
384including packages that link against a version of the R library compiled with
385special options turned on:
386```nix
387with (import <nixpkgs> { });
388
389let R = pkgs.R.override { enableStrictBarrier = true; };
390in
391haskell.lib.buildStackProject {
392 name = "HaskellR";
393 buildInputs = [ R zeromq zlib ];
394}
395```
396
397You can select a particular GHC version to compile with by setting the
398`ghc` attribute as an argument to `buildStackProject`. Better yet, let
399Stack choose what GHC version it wants based on the snapshot specified
400in `stack.yaml` (only works with Stack >= 1.1.3):
401```nix
402{nixpkgs ? import <nixpkgs> { }, ghc ? nixpkgs.ghc}:
403
404with nixpkgs;
405
406let R = pkgs.R.override { enableStrictBarrier = true; };
407in
408haskell.lib.buildStackProject {
409 name = "HaskellR";
410 buildInputs = [ R zeromq zlib ];
411 inherit ghc;
412}
413```
414
415[stack-nix-doc]: http://docs.haskellstack.org/en/stable/nix_integration.html
416
417### How to create ad hoc environments for `nix-shell`
418
419The easiest way to create an ad hoc development environment is to run
420`nix-shell` with the appropriate GHC environment given on the command-line:
421```shell
422nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])"
423```
424
425For more sophisticated use-cases, however, it's more convenient to save the
426desired configuration in a file called `shell.nix` that looks like this:
427```nix
428{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
429let
430 inherit (nixpkgs) pkgs;
431 ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [
432 monad-par mtl
433 ]);
434in
435pkgs.stdenv.mkDerivation {
436 name = "my-haskell-env-0";
437 buildInputs = [ ghc ];
438 shellHook = "eval $(egrep ^export ${ghc}/bin/ghc)";
439}
440```
441
442Now run `nix-shell` --- or even `nix-shell --pure` --- to enter a shell
443environment that has the appropriate compiler in `$PATH`. If you use `--pure`,
444then add all other packages that your development environment needs into the
445`buildInputs` attribute. If you'd like to switch to a different compiler
446version, then pass an appropriate `compiler` argument to the expression, i.e.
447`nix-shell --argstr compiler ghc784`.
448
449If you need such an environment because you'd like to compile a Hackage package
450outside of Nix --- i.e. because you're hacking on the latest version from Git
451---, then the package set provides suitable nix-shell environments for you
452already! Every Haskell package has an `env` attribute that provides a shell
453environment suitable for compiling that particular package. If you'd like to
454hack the `lens` library, for example, then you just have to check out the
455source code and enter the appropriate environment:
456```
457$ cabal get lens-4.11 && cd lens-4.11
458Downloading lens-4.11...
459Unpacking to lens-4.11/
460
461$ nix-shell "<nixpkgs>" -A haskellPackages.lens.env
462[nix-shell:/tmp/lens-4.11]$
463```
464
465At point, you can run `cabal configure`, `cabal build`, and all the other
466development commands. Note that you need `cabal-install` installed in your
467`$PATH` already to use it here --- the `nix-shell` environment does not provide
468it.
469
470## How to create Nix builds for your own private Haskell packages
471
472If your own Haskell packages have build instructions for Cabal, then you can
473convert those automatically into build instructions for Nix using the
474`cabal2nix` utility, which you can install into your profile by running
475`nix-env -i cabal2nix`.
476
477### How to build a stand-alone project
478
479For example, let's assume that you're working on a private project called
480`foo`. To generate a Nix build expression for it, change into the project's
481top-level directory and run the command:
482```shell
483cabal2nix . > foo.nix
484```
485Then write the following snippet into a file called `default.nix`:
486```nix
487{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
488nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { }
489```
490
491Finally, store the following code in a file called `shell.nix`:
492```nix
493{ nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
494(import ./default.nix { inherit nixpkgs compiler; }).env
495```
496
497At this point, you can run `nix-build` to have Nix compile your project and
498install it into a Nix store path. The local directory will contain a symlink
499called `result` after `nix-build` returns that points into that location. Of
500course, passing the flag `--argstr compiler ghc763` allows switching the build
501to any version of GHC currently supported.
502
503Furthermore, you can call `nix-shell` to enter an interactive development
504environment in which you can use `cabal configure` and `cabal build` to develop
505your code. That environment will automatically contain a proper GHC derivation
506with all the required libraries registered as well as all the system-level
507libraries your package might need.
508
509If your package does not depend on any system-level libraries, then it's
510sufficient to run
511```shell
512nix-shell --command "cabal configure"
513```
514once to set up your build. `cabal-install` determines the absolute paths to all
515resources required for the build and writes them into a config file in the
516`dist/` directory. Once that's done, you can run `cabal build` and any other
517command for that project even outside of the `nix-shell` environment. This
518feature is particularly nice for those of us who like to edit their code with
519an IDE, like Emacs' `haskell-mode`, because it's not necessary to start Emacs
520inside of nix-shell just to make it find out the necessary settings for
521building the project; `cabal-install` has already done that for us.
522
523If you want to do some quick-and-dirty hacking and don't want to bother setting
524up a `default.nix` and `shell.nix` file manually, then you can use the
525`--shell` flag offered by `cabal2nix` to have it generate a stand-alone
526`nix-shell` environment for you. With that feature, running
527```shell
528cabal2nix --shell . > shell.nix
529nix-shell --command "cabal configure"
530```
531is usually enough to set up a build environment for any given Haskell package.
532You can even use that generated file to run `nix-build`, too:
533```shell
534nix-build shell.nix
535```
536
537### How to build projects that depend on each other
538
539If you have multiple private Haskell packages that depend on each other, then
540you'll have to register those packages in the Nixpkgs set to make them visible
541for the dependency resolution performed by `callPackage`. First of all, change
542into each of your projects top-level directories and generate a `default.nix`
543file with `cabal2nix`:
544```shell
545cd ~/src/foo && cabal2nix . > default.nix
546cd ~/src/bar && cabal2nix . > default.nix
547```
548Then edit your `~/.config/nixpkgs/config.nix` file to register those builds in the
549default Haskell package set:
550```nix
551{
552 packageOverrides = super: let self = super.pkgs; in
553 {
554 haskellPackages = super.haskellPackages.override {
555 overrides = self: super: {
556 foo = self.callPackage ../src/foo {};
557 bar = self.callPackage ../src/bar {};
558 };
559 };
560 };
561}
562```
563Once that's accomplished, `nix-env -f "<nixpkgs>" -qA haskellPackages` will
564show your packages like any other package from Hackage, and you can build them
565```shell
566nix-build "<nixpkgs>" -A haskellPackages.foo
567```
568or enter an interactive shell environment suitable for building them:
569```shell
570nix-shell "<nixpkgs>" -A haskellPackages.bar.env
571```
572
573## Miscellaneous Topics
574
575### How to build with profiling enabled
576
577Every Haskell package set takes a function called `overrides` that you can use
578to manipulate the package as much as you please. One useful application of this
579feature is to replace the default `mkDerivation` function with one that enables
580library profiling for all packages. To accomplish that add the following
581snippet to your `~/.config/nixpkgs/config.nix` file:
582```nix
583{
584 packageOverrides = super: let self = super.pkgs; in
585 {
586 profiledHaskellPackages = self.haskellPackages.override {
587 overrides = self: super: {
588 mkDerivation = args: super.mkDerivation (args // {
589 enableLibraryProfiling = true;
590 });
591 };
592 };
593 };
594}
595```
596Then, replace instances of `haskellPackages` in the `cabal2nix`-generated
597`default.nix` or `shell.nix` files with `profiledHaskellPackages`.
598
599### How to override package versions in a compiler-specific package set
600
601Nixpkgs provides the latest version of
602[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
603at the time of this writing. This is fine for users of GHC 7.10.x, but GHC
6047.8.4 cannot compile that binary. Now, one way to solve that problem is to
605register an older version of `ghc-events` in the 7.8.x-specific package set.
606The first step is to generate Nix build instructions with `cabal2nix`:
607```shell
608cabal2nix cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix
609```
610Then add the override in `~/.config/nixpkgs/config.nix`:
611```nix
612{
613 packageOverrides = super: let self = super.pkgs; in
614 {
615 haskell = super.haskell // {
616 packages = super.haskell.packages // {
617 ghc784 = super.haskell.packages.ghc784.override {
618 overrides = self: super: {
619 ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
620 };
621 };
622 };
623 };
624 };
625}
626```
627
628This code is a little crazy, no doubt, but it's necessary because the intuitive
629version
630```nix
631{ # ...
632
633 haskell.packages.ghc784 = super.haskell.packages.ghc784.override {
634 overrides = self: super: {
635 ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
636 };
637 };
638}
639```
640doesn't do what we want it to: that code replaces the `haskell` package set in
641Nixpkgs with one that contains only one entry,`packages`, which contains only
642one entry `ghc784`. This override loses the `haskell.compiler` set, and it
643loses the `haskell.packages.ghcXYZ` sets for all compilers but GHC 7.8.4. To
644avoid that problem, we have to perform the convoluted little dance from above,
645iterating over each step in hierarchy.
646
647Once it's accomplished, however, we can install a variant of `ghc-events`
648that's compiled with GHC 7.8.4:
649```shell
650nix-env -f "<nixpkgs>" -iA haskell.packages.ghc784.ghc-events
651```
652Unfortunately, it turns out that this build fails again while executing the
653test suite! Apparently, the release archive on Hackage is missing some data
654files that the test suite requires, so we cannot run it. We accomplish that by
655re-generating the Nix expression with the `--no-check` flag:
656```shell
657cabal2nix --no-check cabal://ghc-events-0.4.3.0 > ~/.nixpkgs/ghc-events-0.4.3.0.nix
658```
659Now the builds succeeds.
660
661Of course, in the concrete example of `ghc-events` this whole exercise is not
662an ideal solution, because `ghc-events` can analyze the output emitted by any
663version of GHC later than 6.12 regardless of the compiler version that was used
664to build the `ghc-events` executable, so strictly speaking there's no reason to
665prefer one built with GHC 7.8.x in the first place. However, for users who
666cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
667older version might be useful.
668
669### How to recover from GHC's infamous non-deterministic library ID bug
670
671GHC and distributed build farms don't get along well:
672
673 - https://ghc.haskell.org/trac/ghc/ticket/4012
674
675When you see an error like this one
676```
677package foo-0.7.1.0 is broken due to missing package
678text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91
679```
680then you have to download and re-install `foo` and all its dependents from
681scratch:
682```shell
683nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \
684 | xargs -L 1 nix-store --repair-path
685```
686
687If you're using additional Hydra servers other than `hydra.nixos.org`, then it
688might be necessary to purge the local caches that store data from those
689machines to disable these binary channels for the duration of the previous
690command, i.e. by running:
691```shell
692rm /nix/var/nix/binary-cache-v3.sqlite
693rm /nix/var/nix/manifests/*
694rm /nix/var/nix/channel-cache/*
695```
696
697### Builds on Darwin fail with `math.h` not found
698
699Users of GHC on Darwin have occasionally reported that builds fail, because the
700compiler complains about a missing include file:
701```
702fatal error: 'math.h' file not found
703```
704The issue has been discussed at length in [ticket
7056390](https://github.com/NixOS/nixpkgs/issues/6390), and so far no good
706solution has been proposed. As a work-around, users who run into this problem
707can configure the environment variables
708```shell
709export NIX_CFLAGS_COMPILE="-idirafter /usr/include"
710export NIX_CFLAGS_LINK="-L/usr/lib"
711```
712in their `~/.bashrc` file to avoid the compiler error.
713
714### Builds using Stack complain about missing system libraries
715
716```
717-- While building package zlib-0.5.4.2 using:
718 runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...]
719Process exited with code: ExitFailure 1
720Logs have been written to: /home/foo/src/stack-ide/.stack-work/logs/zlib-0.5.4.2.log
721
722Configuring zlib-0.5.4.2...
723Setup.hs: Missing dependency on a foreign library:
724* Missing (or bad) header file: zlib.h
725This problem can usually be solved by installing the system package that
726provides this library (you may need the "-dev" version). If the library is
727already installed but in a non-standard location then you can use the flags
728--extra-include-dirs= and --extra-lib-dirs= to specify where it is.
729If the header file does exist, it may contain errors that are caught by the C
730compiler at the preprocessing stage. In this case you can re-run configure
731with the verbosity flag -v3 to see the error messages.
732```
733
734When you run the build inside of the nix-shell environment, the system
735is configured to find `libz.so` without any special flags -- the compiler
736and linker "just know" how to find it. Consequently, Cabal won't record
737any search paths for `libz.so` in the package description, which means
738that the package works fine inside of nix-shell, but once you leave the
739shell the shared object can no longer be found. That issue is by no
740means specific to Stack: you'll have that problem with any other
741Haskell package that's built inside of nix-shell but run outside of that
742environment.
743
744You can remedy this issue in several ways. The easiest is to add a `nix` section
745to the `stack.yaml` like the following:
746```yaml
747nix:
748 enable: true
749 packages: [ zlib ]
750```
751
752Stack's Nix support knows to add `${zlib.out}/lib` and `${zlib.dev}/include`
753as an `--extra-lib-dirs` and `extra-include-dirs`, respectively.
754Alternatively, you can achieve the same effect by hand. First of all, run
755```
756$ nix-build --no-out-link "<nixpkgs>" -A zlib
757/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8
758```
759to find out the store path of the system's zlib library. Now, you can
760
761 1. add that path (plus a "/lib" suffix) to your `$LD_LIBRARY_PATH`
762 environment variable to make sure your system linker finds `libz.so`
763 automatically. It's no pretty solution, but it will work.
764
765 2. As a variant of (1), you can also install any number of system
766 libraries into your user's profile (or some other profile) and point
767 `$LD_LIBRARY_PATH` to that profile instead, so that you don't have to
768 list dozens of those store paths all over the place.
769
770 3. The solution I prefer is to call stack with an appropriate
771 --extra-lib-dirs flag like so:
772 ```shell
773 stack --extra-lib-dirs=/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8/lib build
774 ```
775
776Typically, you'll need `--extra-include-dirs` as well. It's possible
777to add those flag to the project's `stack.yaml` or your user's
778global `~/.stack/global/stack.yaml` file so that you don't have to
779specify them manually every time. But again, you're likely better off
780using Stack's Nix support instead.
781
782The same thing applies to `cabal configure`, of course, if you're
783building with `cabal-install` instead of Stack.
784
785### Creating statically linked binaries
786
787There are two levels of static linking. The first option is to configure the
788build with the Cabal flag `--disable-executable-dynamic`. In Nix expressions,
789this can be achieved by setting the attribute:
790```
791enableSharedExecutables = false;
792```
793That gives you a binary with statically linked Haskell libraries and
794dynamically linked system libraries.
795
796To link both Haskell libraries and system libraries statically, the additional
797flags `--ghc-option=-optl=-static --ghc-option=-optl=-pthread` need to be used.
798In Nix, this is accomplished with:
799```
800configureFlags = [ "--ghc-option=-optl=-static" "--ghc-option=-optl=-pthread" ];
801```
802
803It's important to realize, however, that most system libraries in Nix are
804built as shared libraries only, i.e. there is just no static library
805available that Cabal could link!
806
807### Building GHC with integer-simple
808
809By default GHC implements the Integer type using the
810[GNU Multiple Precision Arithmetic (GMP) library](https://gmplib.org/).
811The implementation can be found in the
812[integer-gmp](http://hackage.haskell.org/package/integer-gmp) package.
813
814A potential problem with this is that GMP is licensed under the
815[GNU Lesser General Public License (LGPL)](http://www.gnu.org/copyleft/lesser.html),
816a kind of "copyleft" license. According to the terms of the LGPL, paragraph 5,
817you may distribute a program that is designed to be compiled and dynamically
818linked with the library under the terms of your choice (i.e., commercially) but
819if your program incorporates portions of the library, if it is linked
820statically, then your program is a "derivative"--a "work based on the
821library"--and according to paragraph 2, section c, you "must cause the whole of
822the work to be licensed" under the terms of the LGPL (including for free).
823
824The LGPL licensing for GMP is a problem for the overall licensing of binary
825programs compiled with GHC because most distributions (and builds) of GHC use
826static libraries. (Dynamic libraries are currently distributed only for macOS.)
827The LGPL licensing situation may be worse: even though
828[The Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license)
829is essentially a "free software" license (BSD3), according to
830paragraph 2 of the LGPL, GHC must be distributed under the terms of the LGPL!
831
832To work around these problems GHC can be build with a slower but LGPL-free
833alternative implemention for Integer called
834[integer-simple](http://hackage.haskell.org/package/integer-simple).
835
836To get a GHC compiler build with `integer-simple` instead of `integer-gmp` use
837the attribute: `haskell.compiler.integer-simple."${ghcVersion}"`.
838For example:
839```
840$ nix-build -E '(import <nixpkgs> {}).haskell.compiler.integer-simple.ghc802'
841...
842$ result/bin/ghc-pkg list | grep integer
843 integer-simple-0.1.1.1
844```
845The following command displays the complete list of GHC compilers build with `integer-simple`:
846```
847$ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler.integer-simple
848haskell.compiler.integer-simple.ghc7102 ghc-7.10.2
849haskell.compiler.integer-simple.ghc7103 ghc-7.10.3
850haskell.compiler.integer-simple.ghc722 ghc-7.2.2
851haskell.compiler.integer-simple.ghc742 ghc-7.4.2
852haskell.compiler.integer-simple.ghc783 ghc-7.8.3
853haskell.compiler.integer-simple.ghc784 ghc-7.8.4
854haskell.compiler.integer-simple.ghc801 ghc-8.0.1
855haskell.compiler.integer-simple.ghc802 ghc-8.0.2
856haskell.compiler.integer-simple.ghcHEAD ghc-8.1.20170106
857```
858
859To get a package set supporting `integer-simple` use the attribute:
860`haskell.packages.integer-simple."${ghcVersion}"`. For example
861use the following to get the `scientific` package build with `integer-simple`:
862```shell
863nix-build -A haskell.packages.integer-simple.ghc802.scientific
864```
865
866### Quality assurance
867
868The `haskell.lib` library includes a number of functions for checking for
869various imperfections in Haskell packages. It's useful to apply these functions
870to your own Haskell packages and integrate that in a Continuous Integration
871server like [hydra](https://nixos.org/hydra/) to assure your packages maintain a
872minimum level of quality. This section discusses some of these functions.
873
874#### failOnAllWarnings
875
876Applying `haskell.lib.failOnAllWarnings` to a Haskell package enables the
877`-Wall` and `-Werror` GHC options to turn all warnings into build failures.
878
879#### buildStrictly
880
881Applying `haskell.lib.buildStrictly` to a Haskell package calls
882`failOnAllWarnings` on the given package to turn all warnings into build
883failures. Additionally the source of your package is gotten from first invoking
884`cabal sdist` to ensure all needed files are listed in the Cabal file.
885
886#### checkUnusedPackages
887
888Applying `haskell.lib.checkUnusedPackages` to a Haskell package invokes
889the [packunused](http://hackage.haskell.org/package/packunused) tool on the
890package. `packunused` complains when it finds packages listed as build-depends
891in the Cabal file which are redundant. For example:
892
893```
894$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.haskell.lib.checkUnusedPackages {} pkgs.haskellPackages.scientific'
895these derivations will be built:
896 /nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv
897...
898detected package components
899~~~~~~~~~~~~~~~~~~~~~~~~~~~
900
901 - library
902 - testsuite(s): test-scientific
903 - benchmark(s): bench-scientific*
904
905(component names suffixed with '*' are not configured to be built)
906
907library
908~~~~~~~
909
910The following package dependencies seem redundant:
911
912 - ghc-prim-0.5.0.0
913
914testsuite(test-scientific)
915~~~~~~~~~~~~~~~~~~~~~~~~~~
916
917no redundant packages dependencies found
918
919builder for ‘/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv’ failed with exit code 1
920error: build of ‘/nix/store/3lc51cxj2j57y3zfpq5i69qbzjpvyci1-scientific-0.3.5.1.drv’ failed
921```
922
923As you can see, `packunused` finds out that although the testsuite component has
924no redundant dependencies the library component of `scientific-0.3.5.1` depends
925on `ghc-prim` which is unused in the library.
926
927## Other resources
928
929 - The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
930 provides an introduction into Haskell NG aimed at beginners. The slides are
931 available at http://cryp.to/nixos-meetup-3-slides.pdf and also -- in a form
932 ready for cut & paste -- at
933 https://github.com/NixOS/cabal2nix/blob/master/doc/nixos-meetup-3-slides.md.
934
935 - Another Youtube video is [Escaping Cabal Hell with Nix](https://www.youtube.com/watch?v=mQd3s57n_2Y),
936 which discusses the subject of Haskell development with Nix but also provides
937 a basic introduction to Nix as well, i.e. it's suitable for viewers with
938 almost no prior Nix experience.
939
940 - Oliver Charles wrote a very nice [Tutorial how to develop Haskell packages with Nix](http://wiki.ocharles.org.uk/Nix).
941
942 - The *Journey into the Haskell NG infrastructure* series of postings
943 describe the new Haskell infrastructure in great detail:
944
945 - [Part 1](https://nixos.org/nix-dev/2015-January/015591.html)
946 explains the differences between the old and the new code and gives
947 instructions how to migrate to the new setup.
948
949 - [Part 2](https://nixos.org/nix-dev/2015-January/015608.html)
950 looks in-depth at how to tweak and configure your setup by means of
951 overrides.
952
953 - [Part 3](https://nixos.org/nix-dev/2015-April/016912.html)
954 describes the infrastructure that keeps the Haskell package set in Nixpkgs
955 up-to-date.