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