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