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