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
16 error: selector ‘alex’ matches no derivations
17 $ nix-env -qa ghc
18 ghc-7.10.2
19
20The Haskell package set is not registered in the top-level namespace because it
21is *huge*. If all Haskell packages were visible to these commands, then
22name-based search/install operations would be much slower than they are now. We
23avoided that by keeping all Haskell-related packages in a separate attribute
24set called `haskellPackages`, which the following command will list:
25
26 $ nix-env -f "<nixpkgs>" -qaP -A haskellPackages
27 haskellPackages.a50 a50-0.5
28 haskellPackages.abacate haskell-abacate-0.0.0.0
29 haskellPackages.abcBridge haskell-abcBridge-0.12
30 haskellPackages.afv afv-0.1.1
31 haskellPackages.alex alex-3.1.4
32 haskellPackages.Allure Allure-0.4.101.1
33 haskellPackages.alms alms-0.6.7
34 [... some 8000 entries omitted ...]
35
36To install any of those packages into your profile, refer to them by their
37attribute path (first column):
38
39 $ nix-env -f "<nixpkgs>" -iA haskellPackages.Allure ...
40
41The attribute path of any Haskell packages corresponds to the name of that
42particular package on Hackage: the package `cabal-install` has the attribute
43`haskellPackages.cabal-install`, and so on. (Actually, this convention causes
44trouble with packages like `3dmodels` and `4Blocks`, because these names are
45invalid identifiers in the Nix language. The issue of how to deal with these
46rare corner cases is currently unresolved.)
47
48Haskell packages who's Nix name (second column) begins with a `haskell-` prefix
49are packages that provide a library whereas packages without that prefix
50provide just executables. Libraries may provide executables too, though: the
51package `haskell-pandoc`, for example, installs both a library and an
52application. You can install and use Haskell executables just like any other
53program in Nixpkgs, but using Haskell libraries for development is a bit
54trickier and we'll address that subject in great detail in section [How to
55create a development environment].
56
57Attribute paths are deterministic inside of Nixpkgs, but the path necessary to
58reach Nixpkgs varies from system to system. We dodged that problem by giving
59`nix-env` an explicit `-f "<nixpkgs>"` parameter, but if you call `nix-env`
60without that flag, then chances are the invocation fails:
61
62 $ nix-env -iA haskellPackages.cabal-install
63 error: attribute ‘haskellPackages’ in selection path
64 ‘haskellPackages.cabal-install’ not found
65
66On NixOS, for example, Nixpkgs does *not* exist in the top-level namespace by
67default. To figure out the proper attribute path, it's easiest to query for the
68path of a well-known Nixpkgs package, i.e.:
69
70 $ nix-env -qaP coreutils
71 nixos.coreutils coreutils-8.23
72
73If your system responds like that (most NixOS installations will), then the
74attribute path to `haskellPackages` is `nixos.haskellPackages`. Thus, if you
75want to use `nix-env` without giving an explicit `-f` flag, then that's the way
76to do it:
77
78 $ nix-env -qaP -A nixos.haskellPackages
79 $ nix-env -iA nixos.haskellPackages.cabal-install
80
81Our current default compiler is GHC 7.10.x and the `haskellPackages` set
82contains packages built with that particular version. Nixpkgs contains the
83latest major release of every GHC since 6.10.4, however, and there is a whole
84family of package sets available that defines Hackage packages built with each
85of those compilers, too:
86
87 $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc6123
88 $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc763
89
90The name `haskellPackages` is really just a synonym for
91`haskell.packages.ghc7102`, because we prefer that package set internally and
92recommend it to our users as their default choice, but ultimately you are free
93to compile your Haskell packages with any GHC version you please. The following
94command displays the complete list of available compilers:
95
96 $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler
97 haskell.compiler.ghc6104 ghc-6.10.4
98 haskell.compiler.ghc6123 ghc-6.12.3
99 haskell.compiler.ghc704 ghc-7.0.4
100 haskell.compiler.ghc722 ghc-7.2.2
101 haskell.compiler.ghc742 ghc-7.4.2
102 haskell.compiler.ghc763 ghc-7.6.3
103 haskell.compiler.ghc784 ghc-7.8.4
104 haskell.compiler.ghc7102 ghc-7.10.2
105 haskell.compiler.ghcHEAD ghc-7.11.20150402
106 haskell.compiler.ghcNokinds ghc-nokinds-7.11.20150704
107 haskell.compiler.ghcjs ghcjs-0.1.0
108 haskell.compiler.jhc jhc-0.8.2
109 haskell.compiler.uhc uhc-1.1.9.0
110
111We have no package sets for `jhc` or `uhc` yet, unfortunately, but for every
112version of GHC listed above, there exists a package set based on that compiler.
113Also, the attributes `haskell.compiler.ghcXYC` and
114`haskell.packages.ghcXYC.ghc` are synonymous for the sake of convenience.
115
116## How to create a development environment
117
118### How to install a compiler
119
120A simple development environment consists of a Haskell compiler and one or both
121of the tools `cabal-install` and `stack`. We saw in section
122[How to install Haskell packages] how you can install those programs into your
123user profile:
124
125 $ nix-env -f "<nixpkgs>" -iA haskellPackages.ghc haskellPackages.cabal-install
126
127Instead of the default package set `haskellPackages`, you can also use the more
128precise name `haskell.compiler.ghc7102`, which has the advantage that it refers
129to the same GHC version regardless of what Nixpkgs considers "default" at any
130given time.
131
132Once you've made those tools available in `$PATH`, it's possible to build
133Hackage packages the same way people without access to Nix do it all the time:
134
135 $ cabal get lens-4.11 && cd lens-4.11
136 $ cabal install -j --dependencies-only
137 $ cabal configure
138 $ cabal build
139
140If you enjoy working with Cabal sandboxes, then that's entirely possible too:
141just execute the command
142
143 $ cabal sandbox init
144
145before installing the required dependencies.
146
147The `nix-shell` utility makes it easy to switch to a different compiler
148version; just enter the Nix shell environment with the command
149
150 $ nix-shell -p haskell.compiler.ghc784
151
152to bring GHC 7.8.4 into `$PATH`. Alternatively, you can use Stack instead of
153`nix-shell` directly to select compiler versions and other build tools
154per-project. It uses `nix-shell` under the hood when Nix support is turned on.
155See [How to build a Haskell project using Stack].
156
157If you're using `cabal-install`, re-running `cabal configure` inside the spawned
158shell switches your build to use that compiler instead. If you're working on
159a project that doesn't depend on any additional system libraries outside of GHC,
160then it's even sufficient to just run the `cabal configure` command inside of
161the shell:
162
163 $ nix-shell -p haskell.compiler.ghc784 --command "cabal configure"
164
165Afterwards, all other commands like `cabal build` work just fine in any shell
166environment, because the configure phase recorded the absolute paths to all
167required tools like GHC in its build configuration inside of the `dist/`
168directory. Please note, however, that `nix-collect-garbage` can break such an
169environment because the Nix store paths created by `nix-shell` aren't "alive"
170anymore once `nix-shell` has terminated. If you find that your Haskell builds
171no longer work after garbage collection, then you'll have to re-run `cabal
172configure` inside of a new `nix-shell` environment.
173
174### How to install a compiler with libraries
175
176GHC expects to find all installed libraries inside of its own `lib` directory.
177This approach works fine on traditional Unix systems, but it doesn't work for
178Nix, because GHC's store path is immutable once it's built. We cannot install
179additional libraries into that location. As a consequence, our copies of GHC
180don't know any packages except their own core libraries, like `base`,
181`containers`, `Cabal`, etc.
182
183We can register additional libraries to GHC, however, using a special build
184function called `ghcWithPackages`. That function expects one argument: a
185function that maps from an attribute set of Haskell packages to a list of
186packages, which determines the libraries known to that particular version of
187GHC. For example, the Nix expression `ghcWithPackages (pkgs: [pkgs.mtl])`
188generates a copy of GHC that has the `mtl` library registered in addition to
189its normal core packages:
190
191 $ nix-shell -p "haskellPackages.ghcWithPackages (pkgs: [pkgs.mtl])"
192
193 [nix-shell:~]$ ghc-pkg list mtl
194 /nix/store/zy79...-ghc-7.10.2/lib/ghc-7.10.2/package.conf.d:
195 mtl-2.2.1
196
197This function allows users to define their own development environment by means
198of an override. After adding the following snippet to `~/.nixpkgs/config.nix`,
199
200 {
201 packageOverrides = super: let self = super.pkgs; in
202 {
203 myHaskellEnv = self.haskell.packages.ghc7102.ghcWithPackages
204 (haskellPackages: with haskellPackages; [
205 # libraries
206 arrows async cgi criterion
207 # tools
208 cabal-install haskintex
209 ]);
210 };
211 }
212
213it's possible to install that compiler with `nix-env -f "<nixpkgs>" -iA
214myHaskellEnv`. If you'd like to switch that development environment to a
215different version of GHC, just replace the `ghc7102` bit in the previous
216definition with the appropriate name. Of course, it's also possible to define
217any number of these development environments! (You can't install two of them
218into the same profile at the same time, though, because that would result in
219file conflicts.)
220
221The generated `ghc` program is a wrapper script that re-directs the real
222GHC executable to use a new `lib` directory --- one that we specifically
223constructed to contain all those packages the user requested:
224
225 $ cat $(type -p ghc)
226 #! /nix/store/xlxj...-bash-4.3-p33/bin/bash -e
227 export NIX_GHC=/nix/store/19sm...-ghc-7.10.2/bin/ghc
228 export NIX_GHCPKG=/nix/store/19sm...-ghc-7.10.2/bin/ghc-pkg
229 export NIX_GHC_DOCDIR=/nix/store/19sm...-ghc-7.10.2/share/doc/ghc/html
230 export NIX_GHC_LIBDIR=/nix/store/19sm...-ghc-7.10.2/lib/ghc-7.10.2
231 exec /nix/store/j50p...-ghc-7.10.2/bin/ghc "-B$NIX_GHC_LIBDIR" "$@"
232
233The variables `$NIX_GHC`, `$NIX_GHCPKG`, etc. point to the *new* store path
234`ghcWithPackages` constructed specifically for this environment. The last line
235of the wrapper script then executes the real `ghc`, but passes the path to the
236new `lib` directory using GHC's `-B` flag.
237
238The purpose of those environment variables is to work around an impurity in the
239popular [ghc-paths](http://hackage.haskell.org/package/ghc-paths) library. That
240library promises to give its users access to GHC's installation paths. Only,
241the library can't possible know that path when it's compiled, because the path
242GHC considers its own is determined only much later, when the user configures
243it through `ghcWithPackages`. So we [patched
244ghc-paths](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/patches/ghc-paths-nix.patch)
245to return the paths found in those environment variables at run-time rather
246than trying to guess them at compile-time.
247
248To make sure that mechanism works properly all the time, we recommend that you
249set those variables to meaningful values in your shell environment, too, i.e.
250by adding the following code to your `~/.bashrc`:
251
252 if type >/dev/null 2>&1 -p ghc; then
253 eval "$(egrep ^export "$(type -p ghc)")"
254 fi
255
256If you are certain that you'll use only one GHC environment which is located in
257your user profile, then you can use the following code, too, which has the
258advantage that it doesn't contain any paths from the Nix store, i.e. those
259settings always remain valid even if a `nix-env -u` operation updates the GHC
260environment in your profile:
261
262 if [ -e ~/.nix-profile/bin/ghc ]; then
263 export NIX_GHC="$HOME/.nix-profile/bin/ghc"
264 export NIX_GHCPKG="$HOME/.nix-profile/bin/ghc-pkg"
265 export NIX_GHC_DOCDIR="$HOME/.nix-profile/share/doc/ghc/html"
266 export NIX_GHC_LIBDIR="$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)"
267 fi
268
269### How to install a compiler with libraries, hoogle and documentation indexes
270
271If you plan to use your environment for interactive programming, not just
272compiling random Haskell code, you might want to replace `ghcWithPackages` in
273all the listings above with `ghcWithHoogle`.
274
275This environment generator not only produces an environment with GHC and all
276the specified libraries, but also generates a `hoogle` and `haddock` indexes
277for all the packages, and provides a wrapper script around `hoogle` binary that
278uses all those things. A precise name for this thing would be
279"`ghcWithPackagesAndHoogleAndDocumentationIndexes`", which is, regrettably, too
280long and scary.
281
282For example, installing the following environment
283
284 {
285 packageOverrides = super: let self = super.pkgs; in
286 {
287 myHaskellEnv = self.haskellPackages.ghcWithHoogle
288 (haskellPackages: with haskellPackages; [
289 # libraries
290 arrows async cgi criterion
291 # tools
292 cabal-install haskintex
293 ]);
294 };
295 }
296
297allows one to browse module documentation index [not too dissimilar to
298this](https://downloads.haskell.org/~ghc/latest/docs/html/libraries/index.html)
299for all the specified packages and their dependencies by directing a browser of
300choice to `~/.nix-profiles/share/doc/hoogle/index.html` (or
301`/run/current-system/sw/share/doc/hoogle/index.html` in case you put it in
302`environment.systemPackages` in NixOS).
303
304After you've marveled enough at that try adding the following to your
305`~/.ghc/ghci.conf`
306
307 :def hoogle \s -> return $ ":! hoogle search -cl --count=15 \"" ++ s ++ "\""
308 :def doc \s -> return $ ":! hoogle search -cl --info \"" ++ s ++ "\""
309
310and test it by typing into `ghci`:
311
312 :hoogle a -> a
313 :doc a -> a
314
315Be sure to note the links to `haddock` files in the output. With any modern and
316properly configured terminal emulator you can just click those links to
317navigate there.
318
319Finally, you can run
320
321 hoogle server -p 8080
322
323and navigate to http://localhost:8080/ for your own local
324[Hoogle](https://www.haskell.org/hoogle/). Note, however, that Firefox and
325possibly other browsers disallow navigation from `http:` to `file:` URIs for
326security reasons, which might be quite an inconvenience. See [this
327page](http://kb.mozillazine.org/Links_to_local_pages_do_not_work) for
328workarounds.
329
330### How to build a Haskell project using Stack
331
332[Stack](http://haskellstack.org) is a popular build tool for Haskell projects.
333It has first-class support for Nix. Stack can optionally use Nix to
334automatically select the right version of GHC and other build tools to build,
335test and execute apps in an existing project downloaded from somewhere on the
336Internet. Pass the `--nix` flag to any `stack` command to do so, e.g.
337
338 $ git clone --recursive http://github.com/yesodweb/wai
339 $ cd wai
340 $ stack --nix build
341
342If you want `stack` to use Nix by default, you can add a `nix` section to the
343`stack.yaml` file, as explained in the [Stack documentation][stack-nix-doc]. For
344example:
345
346 nix:
347 enable: true
348 packages: [pkgconfig zeromq zlib]
349
350The example configuration snippet above tells Stack to create an ad hoc
351environment for `nix-shell` as in the below section, in which the `pkgconfig`,
352`zeromq` and `zlib` packages from Nixpkgs are available. All `stack` commands
353will implicitly be executed inside this ad hoc environment.
354
355Some projects have more sophisticated needs. For examples, some ad hoc
356environments might need to expose Nixpkgs packages compiled in a certain way, or
357with extra environment variables. In these cases, you'll need a `shell` field
358instead of `packages`:
359
360 nix:
361 enable: true
362 shell-file: shell.nix
363
364For more on how to write a `shell.nix` file see the below section. You'll need
365to express a derivation. Note that Nixpkgs ships with a convenience wrapper
366function around `mkDerivation` called `haskell.lib.buildStackProject` to help you
367create this derivation in exactly the way Stack expects. All of the same inputs
368as `mkDerivation` can be provided. For example, to build a Stack project that
369including packages that link against a version of the R library compiled with
370special options turned on:
371
372 with (import <nixpkgs> { });
373
374 let R = pkgs.R.override { enableStrictBarrier = true; };
375 in
376 haskell.lib.buildStackProject {
377 name = "HaskellR";
378 buildInputs = [ R zeromq zlib ];
379 }
380
381You can select a particular GHC version to compile with by setting the
382`ghc` attribute as an argument to `buildStackProject`. Better yet, let
383Stack choose what GHC version it wants based on the snapshot specified
384in `stack.yaml` (only works with Stack >= 1.1.3):
385
386 {nixpkgs ? import <nixpkgs> { }, ghc ? nixpkgs.ghc}
387
388 with nixpkgs;
389
390 let R = pkgs.R.override { enableStrictBarrier = true; };
391 in
392 haskell.lib.buildStackProject {
393 name = "HaskellR";
394 buildInputs = [ R zeromq zlib ];
395 inherit ghc;
396 }
397
398[stack-nix-doc]: http://docs.haskellstack.org/en/stable/nix_integration.html
399
400### How to create ad hoc environments for `nix-shell`
401
402The easiest way to create an ad hoc development environment is to run
403`nix-shell` with the appropriate GHC environment given on the command-line:
404
405 nix-shell -p "haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])"
406
407For more sophisticated use-cases, however, it's more convenient to save the
408desired configuration in a file called `shell.nix` that looks like this:
409
410 { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
411 let
412 inherit (nixpkgs) pkgs;
413 ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [
414 monad-par mtl
415 ]);
416 in
417 pkgs.stdenv.mkDerivation {
418 name = "my-haskell-env-0";
419 buildInputs = [ ghc ];
420 shellHook = "eval $(egrep ^export ${ghc}/bin/ghc)";
421 }
422
423Now run `nix-shell` --- or even `nix-shell --pure` --- to enter a shell
424environment that has the appropriate compiler in `$PATH`. If you use `--pure`,
425then add all other packages that your development environment needs into the
426`buildInputs` attribute. If you'd like to switch to a different compiler
427version, then pass an appropriate `compiler` argument to the expression, i.e.
428`nix-shell --argstr compiler ghc784`.
429
430If you need such an environment because you'd like to compile a Hackage package
431outside of Nix --- i.e. because you're hacking on the latest version from Git
432---, then the package set provides suitable nix-shell environments for you
433already! Every Haskell package has an `env` attribute that provides a shell
434environment suitable for compiling that particular package. If you'd like to
435hack the `lens` library, for example, then you just have to check out the
436source code and enter the appropriate environment:
437
438 $ cabal get lens-4.11 && cd lens-4.11
439 Downloading lens-4.11...
440 Unpacking to lens-4.11/
441
442 $ nix-shell "<nixpkgs>" -A haskellPackages.lens.env
443 [nix-shell:/tmp/lens-4.11]$
444
445At point, you can run `cabal configure`, `cabal build`, and all the other
446development commands. Note that you need `cabal-install` installed in your
447`$PATH` already to use it here --- the `nix-shell` environment does not provide
448it.
449
450## How to create Nix builds for your own private Haskell packages
451
452If your own Haskell packages have build instructions for Cabal, then you can
453convert those automatically into build instructions for Nix using the
454`cabal2nix` utility, which you can install into your profile by running
455`nix-env -i cabal2nix`.
456
457### How to build a stand-alone project
458
459For example, let's assume that you're working on a private project called
460`foo`. To generate a Nix build expression for it, change into the project's
461top-level directory and run the command:
462
463 $ cabal2nix . >foo.nix
464
465Then write the following snippet into a file called `default.nix`:
466
467 { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
468 nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { }
469
470Finally, store the following code in a file called `shell.nix`:
471
472 { nixpkgs ? import <nixpkgs> {}, compiler ? "ghc7102" }:
473 (import ./default.nix { inherit nixpkgs compiler; }).env
474
475At this point, you can run `nix-build` to have Nix compile your project and
476install it into a Nix store path. The local directory will contain a symlink
477called `result` after `nix-build` returns that points into that location. Of
478course, passing the flag `--argstr compiler ghc763` allows switching the build
479to any version of GHC currently supported.
480
481Furthermore, you can call `nix-shell` to enter an interactive development
482environment in which you can use `cabal configure` and `cabal build` to develop
483your code. That environment will automatically contain a proper GHC derivation
484with all the required libraries registered as well as all the system-level
485libraries your package might need.
486
487If your package does not depend on any system-level libraries, then it's
488sufficient to run
489
490 $ nix-shell --command "cabal configure"
491
492once to set up your build. `cabal-install` determines the absolute paths to all
493resources required for the build and writes them into a config file in the
494`dist/` directory. Once that's done, you can run `cabal build` and any other
495command for that project even outside of the `nix-shell` environment. This
496feature is particularly nice for those of us who like to edit their code with
497an IDE, like Emacs' `haskell-mode`, because it's not necessary to start Emacs
498inside of nix-shell just to make it find out the necessary settings for
499building the project; `cabal-install` has already done that for us.
500
501If you want to do some quick-and-dirty hacking and don't want to bother setting
502up a `default.nix` and `shell.nix` file manually, then you can use the
503`--shell` flag offered by `cabal2nix` to have it generate a stand-alone
504`nix-shell` environment for you. With that feature, running
505
506 $ cabal2nix --shell . >shell.nix
507 $ nix-shell --command "cabal configure"
508
509is usually enough to set up a build environment for any given Haskell package.
510You can even use that generated file to run `nix-build`, too:
511
512 $ nix-build shell.nix
513
514### How to build projects that depend on each other
515
516If you have multiple private Haskell packages that depend on each other, then
517you'll have to register those packages in the Nixpkgs set to make them visible
518for the dependency resolution performed by `callPackage`. First of all, change
519into each of your projects top-level directories and generate a `default.nix`
520file with `cabal2nix`:
521
522 $ cd ~/src/foo && cabal2nix . >default.nix
523 $ cd ~/src/bar && cabal2nix . >default.nix
524
525Then edit your `~/.nixpkgs/config.nix` file to register those builds in the
526default Haskell package set:
527
528 {
529 packageOverrides = super: let self = super.pkgs; in
530 {
531 haskellPackages = super.haskellPackages.override {
532 overrides = self: super: {
533 foo = self.callPackage ../src/foo {};
534 bar = self.callPackage ../src/bar {};
535 };
536 };
537 };
538 }
539
540Once that's accomplished, `nix-env -f "<nixpkgs>" -qA haskellPackages` will
541show your packages like any other package from Hackage, and you can build them
542
543 $ nix-build "<nixpkgs>" -A haskellPackages.foo
544
545or enter an interactive shell environment suitable for building them:
546
547 $ nix-shell "<nixpkgs>" -A haskellPackages.bar.env
548
549## Miscellaneous Topics
550
551### How to build with profiling enabled
552
553Every Haskell package set takes a function called `overrides` that you can use
554to manipulate the package as much as you please. One useful application of this
555feature is to replace the default `mkDerivation` function with one that enables
556library profiling for all packages. To accomplish that, add configure the
557following snippet in your `~/.nixpkgs/config.nix` file:
558
559 {
560 packageOverrides = super: let self = super.pkgs; in
561 {
562 profiledHaskellPackages = self.haskellPackages.override {
563 overrides = self: super: {
564 mkDerivation = args: super.mkDerivation (args // {
565 enableLibraryProfiling = true;
566 });
567 };
568 };
569 };
570 }
571
572Then, replace instances of `haskellPackages` in the `cabal2nix`-generated
573`default.nix` or `shell.nix` files with `profiledHaskellPackages`.
574
575### How to override package versions in a compiler-specific package set
576
577Nixpkgs provides the latest version of
578[`ghc-events`](http://hackage.haskell.org/package/ghc-events), which is 0.4.4.0
579at the time of this writing. This is fine for users of GHC 7.10.x, but GHC
5807.8.4 cannot compile that binary. Now, one way to solve that problem is to
581register an older version of `ghc-events` in the 7.8.x-specific package set.
582The first step is to generate Nix build instructions with `cabal2nix`:
583
584 $ cabal2nix cabal://ghc-events-0.4.3.0 >~/.nixpkgs/ghc-events-0.4.3.0.nix
585
586Then add the override in `~/.nixpkgs/config.nix`:
587
588 {
589 packageOverrides = super: let self = super.pkgs; in
590 {
591 haskell = super.haskell // {
592 packages = super.haskell.packages // {
593 ghc784 = super.haskell.packages.ghc784.override {
594 overrides = self: super: {
595 ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
596 };
597 };
598 };
599 };
600 };
601 }
602
603This code is a little crazy, no doubt, but it's necessary because the intuitive
604version
605
606 haskell.packages.ghc784 = super.haskell.packages.ghc784.override {
607 overrides = self: super: {
608 ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
609 };
610 };
611
612doesn't do what we want it to: that code replaces the `haskell` package set in
613Nixpkgs with one that contains only one entry,`packages`, which contains only
614one entry `ghc784`. This override loses the `haskell.compiler` set, and it
615loses the `haskell.packages.ghcXYZ` sets for all compilers but GHC 7.8.4. To
616avoid that problem, we have to perform the convoluted little dance from above,
617iterating over each step in hierarchy.
618
619Once it's accomplished, however, we can install a variant of `ghc-events`
620that's compiled with GHC 7.8.4:
621
622 nix-env -f "<nixpkgs>" -iA haskell.packages.ghc784.ghc-events
623
624Unfortunately, it turns out that this build fails again while executing the
625test suite! Apparently, the release archive on Hackage is missing some data
626files that the test suite requires, so we cannot run it. We accomplish that by
627re-generating the Nix expression with the `--no-check` flag:
628
629 $ cabal2nix --no-check cabal://ghc-events-0.4.3.0 >~/.nixpkgs/ghc-events-0.4.3.0.nix
630
631Now the builds succeeds.
632
633Of course, in the concrete example of `ghc-events` this whole exercise is not
634an ideal solution, because `ghc-events` can analyze the output emitted by any
635version of GHC later than 6.12 regardless of the compiler version that was used
636to build the `ghc-events' executable, so strictly speaking there's no reason to
637prefer one built with GHC 7.8.x in the first place. However, for users who
638cannot use GHC 7.10.x at all for some reason, the approach of downgrading to an
639older version might be useful.
640
641### How to recover from GHC's infamous non-deterministic library ID bug
642
643GHC and distributed build farms don't get along well:
644
645 https://ghc.haskell.org/trac/ghc/ticket/4012
646
647When you see an error like this one
648
649 package foo-0.7.1.0 is broken due to missing package
650 text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91
651
652then you have to download and re-install `foo` and all its dependents from
653scratch:
654
655 # nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \
656 | xargs -L 1 nix-store --repair-path
657
658If you're using additional Hydra servers other than `hydra.nixos.org`, then it
659might be necessary to purge the local caches that store data from those
660machines to disable these binary channels for the duration of the previous
661command, i.e. by running:
662
663 rm /nix/var/nix/binary-cache-v3.sqlite
664 rm /nix/var/nix/manifests/*
665 rm /nix/var/nix/channel-cache/*
666
667### How to use the Haste Haskell-to-Javascript transpiler
668
669Open a shell with `haste-compiler` and `haste-cabal-install` (you don't actually need
670`node`, but it can be useful to test stuff):
671
672 $ nix-shell -p "haskellPackages.ghcWithPackages (self: with self; [haste-cabal-install haste-compiler])" -p nodejs
673
674You may not need the following step but if `haste-boot` fails to compile all the
675packages it needs, this might do the trick
676
677 $ haste-cabal update
678
679`haste-boot` builds a set of core libraries so that they can be used from Javascript
680transpiled programs:
681
682 $ haste-boot
683
684Transpile and run a "Hello world" program:
685
686 $ echo 'module Main where main = putStrLn "Hello world"' > hello-world.hs
687 $ hastec --onexec hello-world.hs
688 $ node hello-world.js
689 Hello world
690
691### Builds on Darwin fail with `math.h` not found
692
693Users of GHC on Darwin have occasionally reported that builds fail, because the
694compiler complains about a missing include file:
695
696 fatal error: 'math.h' file not found
697
698The issue has been discussed at length in [ticket
6996390](https://github.com/NixOS/nixpkgs/issues/6390), and so far no good
700solution has been proposed. As a work-around, users who run into this problem
701can configure the environment variables
702
703 export NIX_CFLAGS_COMPILE="-idirafter /usr/include"
704 export NIX_CFLAGS_LINK="-L/usr/lib"
705
706in their `~/.bashrc` file to avoid the compiler error.
707
708### Builds using Stack complain about missing system libraries
709
710 -- While building package zlib-0.5.4.2 using:
711 runhaskell -package=Cabal-1.22.4.0 -clear-package-db [... lots of flags ...]
712 Process exited with code: ExitFailure 1
713 Logs have been written to: /home/foo/src/stack-ide/.stack-work/logs/zlib-0.5.4.2.log
714
715 Configuring zlib-0.5.4.2...
716 Setup.hs: Missing dependency on a foreign library:
717 * Missing (or bad) header file: zlib.h
718 This problem can usually be solved by installing the system package that
719 provides this library (you may need the "-dev" version). If the library is
720 already installed but in a non-standard location then you can use the flags
721 --extra-include-dirs= and --extra-lib-dirs= to specify where it is.
722 If the header file does exist, it may contain errors that are caught by the C
723 compiler at the preprocessing stage. In this case you can re-run configure
724 with the verbosity flag -v3 to see the error messages.
725
726When you run the build inside of the nix-shell environment, the system
727is configured to find libz.so without any special flags -- the compiler
728and linker "just know" how to find it. Consequently, Cabal won't record
729any search paths for libz.so in the package description, which means
730that the package works fine inside of nix-shell, but once you leave the
731shell the shared object can no longer be found. That issue is by no
732means specific to Stack: you'll have that problem with any other
733Haskell package that's built inside of nix-shell but run outside of that
734environment.
735
736You can remedy this issue in several ways. The easiest is to add a `nix` section
737to the `stack.yaml` like the following:
738
739 nix:
740 enable: true
741 packages: [ zlib ]
742
743Stack's Nix support knows to add `${zlib.out}/lib` and `${zlib.dev}/include` as an
744`--extra-lib-dirs` and `extra-include-dirs`, respectively. Alternatively, you
745can achieve the same effect by hand. First of all, run
746
747 $ nix-build --no-out-link "<nixpkgs>" -A zlib
748 /nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8
749
750to find out the store path of the system's zlib library. Now, you can
751
7521) add that path (plus a "/lib" suffix) to your $LD_LIBRARY_PATH
753 environment variable to make sure your system linker finds libz.so
754 automatically. It's no pretty solution, but it will work.
755
7562) As a variant of (1), you can also install any number of system
757 libraries into your user's profile (or some other profile) and point
758 $LD_LIBRARY_PATH to that profile instead, so that you don't have to
759 list dozens of those store paths all over the place.
760
7613) The solution I prefer is to call stack with an appropriate
762 --extra-lib-dirs flag like so:
763
764 $ stack --extra-lib-dirs=/nix/store/alsvwzkiw4b7ip38l4nlfjijdvg3fvzn-zlib-1.2.8/lib build
765
766 Typically, you'll need --extra-include-dirs as well. It's possible
767 to add those flag to the project's "stack.yaml" or your user's
768 global "~/.stack/global/stack.yaml" file so that you don't have to
769 specify them manually every time. But again, you're likely better off using
770 Stack's Nix support instead.
771
772 The same thing applies to `cabal configure`, of course, if you're
773 building with `cabal-install` instead of Stack.
774
775### Creating statically linked binaries
776
777There are two levels of static linking. The first option is to configure the
778build with the Cabal flag `--disable-executable-dynamic`. In Nix expressions,
779this can be achieved by setting the attribute:
780
781 enableSharedExecutables = false;
782
783That gives you a binary with statically linked Haskell libraries and
784dynamically linked system libraries.
785
786To link both Haskell libraries and system libraries statically, the additional
787flags `--ghc-option=-optl=-static --ghc-option=-optl=-pthread` need to be used.
788In Nix, this is accomplished with:
789
790 configureFlags = [ "--ghc-option=-optl=-static" "--ghc-option=-optl=-pthread" ];
791
792It's important to realize, however, that most system libraries in Nix are built
793as shared libraries only, i.e. there is just no static library available that
794Cabal could link!
795
796
797## Other resources
798
799- The Youtube video [Nix Loves Haskell](https://www.youtube.com/watch?v=BsBhi_r-OeE)
800 provides an introduction into Haskell NG aimed at beginners. The slides are
801 available at http://cryp.to/nixos-meetup-3-slides.pdf and also -- in a form
802 ready for cut & paste -- at
803 https://github.com/NixOS/cabal2nix/blob/master/doc/nixos-meetup-3-slides.md.
804
805- Another Youtube video is [Escaping Cabal Hell with Nix](https://www.youtube.com/watch?v=mQd3s57n_2Y),
806 which discusses the subject of Haskell development with Nix but also provides
807 a basic introduction to Nix as well, i.e. it's suitable for viewers with
808 almost no prior Nix experience.
809
810- Oliver Charles wrote a very nice [Tutorial how to develop Haskell packages with Nix](http://wiki.ocharles.org.uk/Nix).
811
812- The *Journey into the Haskell NG infrastructure* series of postings
813 describe the new Haskell infrastructure in great detail:
814
815 - [Part 1](http://lists.science.uu.nl/pipermail/nix-dev/2015-January/015591.html)
816 explains the differences between the old and the new code and gives
817 instructions how to migrate to the new setup.
818
819 - [Part 2](http://lists.science.uu.nl/pipermail/nix-dev/2015-January/015608.html)
820 looks in-depth at how to tweak and configure your setup by means of
821 overrides.
822
823 - [Part 3](http://lists.science.uu.nl/pipermail/nix-dev/2015-April/016912.html)
824 describes the infrastructure that keeps the Haskell package set in Nixpkgs
825 up-to-date.