doc: add user's guide for the Haskell infrastructure

Resolves https://github.com/NixOS/nixpkgs/issues/4941.

2 files changed, 758 insertions, 0 deletions

diff --git a/doc/haskell-users-guide.xml b/doc/haskell-users-guide.xml
new file mode 100644
index 00000000000..ca6c387e8df
--- /dev/null
+++ b/doc/haskell-users-guide.xml
@@ -0,0 +1,757 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="users-guide-to-the-haskell-infrastructure">
+
+<title>User's Guide to the Haskell Infrastructure</title>
+
+<section xml:id="how-to-install-haskell-packages">
+  <title>How to install Haskell packages</title>
+  <para>
+    Nixpkgs distributes build instructions for all Haskell packages
+    registered on
+    <link xlink:href="http://hackage.haskell.org/">Hackage</link>, but
+    strangely enough normal Nix package lookups don't seem to discover
+    any of them:
+  </para>
+  <programlisting>
+$ nix-env -qa cabal-install
+error: selector ‘cabal-install’ matches no derivations
+
+$ nix-env -i ghc
+error: selector ‘ghc’ matches no derivations
+</programlisting>
+  <para>
+    The Haskell package set is not registered in the top-level namespace
+    because it is <emphasis>huge</emphasis>. If all Haskell packages
+    were visible to these commands, then name-based search/install
+    operations would be much slower than they are now. We avoided that
+    by keeping all Haskell-related packages in a separate attribute set
+    called <literal>haskellPackages</literal>, which the following
+    command will list:
+  </para>
+  <programlisting>
+$ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A haskellPackages
+haskellPackages.a50         a50-0.5
+haskellPackages.abacate     haskell-abacate-0.0.0.0
+haskellPackages.abcBridge   haskell-abcBridge-0.12
+haskellPackages.afv         afv-0.1.1
+haskellPackages.alex        alex-3.1.4
+haskellPackages.Allure      Allure-0.4.101.1
+haskellPackages.alms        alms-0.6.7
+[... some 8000 entries omitted  ...]
+</programlisting>
+  <para>
+    To install any of those packages into your profile, refer to them by
+    their attribute path (first column):
+  </para>
+  <programlisting>
+$ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA haskellPackages.Allure ...
+</programlisting>
+  <para>
+    The attribute path of any Haskell packages corresponds to the name
+    of that particular package on Hackage: the package
+    <literal>cabal-install</literal> has the attribute
+    <literal>haskellPackages.cabal-install</literal>, and so on.
+    (Actually, this convention causes trouble with packages like
+    <literal>3dmodels</literal> and <literal>4Blocks</literal>, because
+    these names are invalid identifiers in the Nix language. The issue
+    of how to deal with these rare corner cases is currently
+    unresolved.)
+  </para>
+  <para>
+    Haskell packages who's Nix name (second column) begins with a
+    <literal>haskell-</literal> prefix are packages that provide a
+    library whereas packages without that prefix provide just
+    executables. Libraries may provide executables too, though: the
+    package <literal>haskell-pandoc</literal>, for example, installs
+    both a library and an application. You can install and use Haskell
+    executables just like any other program in Nixpkgs, but using
+    Haskell libraries for development is a bit trickier and we'll
+    address that subject in great detail in section
+    <link linkend="how-to-create-a-development-environment">How to
+    create a development environment</link>.
+  </para>
+  <para>
+    Attribute paths are deterministic inside of Nixpkgs, but the path
+    necessary to reach Nixpkgs varies from system to system. We dodged
+    that problem by giving <literal>nix-env</literal> an explicit
+    <literal>-f &quot;&lt;nixpkgs&gt;&quot;</literal> parameter, but if
+    you call <literal>nix-env</literal> without that flag, then chances
+    are the invocation fails:
+  </para>
+  <programlisting>
+$ nix-env -iA haskellPackages.cabal-install
+error: attribute ‘haskellPackages’ in selection path
+       ‘haskellPackages.cabal-install’ not found
+</programlisting>
+  <para>
+    On NixOS, for example, Nixpkgs does <emphasis>not</emphasis> exist
+    in the top-level namespace by default. To figure out the proper
+    attribute path, it's easiest to query for the path of a well-known
+    Nixpkgs package, i.e.:
+  </para>
+  <programlisting>
+$ nix-env -qaP coreutils
+nixos.pkgs.coreutils  coreutils-8.23
+</programlisting>
+  <para>
+    If your system responds like that (most NixOS installatios will),
+    then the attribute path to <literal>haskellPackages</literal> is
+    <literal>nixos.pkgs.haskellPackages</literal>. Thus, if you want to
+    use <literal>nix-env</literal> without giving an explicit
+    <literal>-f</literal> flag, then that's the way to do it:
+  </para>
+  <programlisting>
+$ nix-env -qaP -A nixos.pkgs.haskellPackages
+$ nix-env -iA nixos.pkgs.haskellPackages.cabal-install
+</programlisting>
+  <para>
+    Our current default compiler is GHC 7.10.x and the
+    <literal>haskellPackages</literal> set contains packages built with
+    that particular version. Nixpkgs contains the latest major release
+    of every GHC since 6.10.4, however, and there is a whole family of
+    package sets available that defines Hackage packages built with each
+    of those compilers, too:
+  </para>
+  <programlisting>
+$ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A haskell.packages.ghc6123
+$ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A haskell.packages.ghc763
+</programlisting>
+  <para>
+    The name <literal>haskellPackages</literal> is really just a synonym
+    for <literal>haskell.packages.ghc7101</literal>, because we prefer
+    that package set internally and recommend it to our users as their
+    default choice, but ultimately you are free to compile your Haskell
+    packages with any GHC version you please. The following command
+    displays the complete list of available compilers:
+  </para>
+  <programlisting>
+$ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qaP -A haskell.compiler
+haskell.compiler.ghc6104        ghc-6.10.4
+haskell.compiler.ghc6123        ghc-6.12.3
+haskell.compiler.ghc704         ghc-7.0.4
+haskell.compiler.ghc722         ghc-7.2.2
+haskell.compiler.ghc742         ghc-7.4.2
+haskell.compiler.ghc763         ghc-7.6.3
+haskell.compiler.ghc784         ghc-7.8.4
+haskell.compiler.ghc7101        ghc-7.10.1
+haskell.compiler.ghcHEAD        ghc-7.11.20150402
+haskell.compiler.ghcjs          ghcjs-0.1.0
+haskell.compiler.jhc            jhc-0.8.2
+haskell.compiler.uhc            uhc-1.1.9.0
+</programlisting>
+  <para>
+    We have no package sets for <literal>jhc</literal> or
+    <literal>uhc</literal> yet, unfortunately, but for every version of
+    GHC listed above, there exists a package set based on that compiler.
+    Also, the attributes <literal>haskell.compiler.ghcXYC</literal> and
+    <literal>haskell.packages.ghcXYC.ghc</literal> are synonymous for
+    the sake of convenience.
+  </para>
+</section>
+<section xml:id="how-to-create-a-development-environment">
+  <title>How to create a development environment</title>
+  <section xml:id="how-to-install-a-compiler">
+    <title>How to install a compiler</title>
+    <para>
+      A simple development environment consists of a Haskell compiler
+      and the tool <literal>cabal-install</literal>, and we saw in
+      section <link linkend="how-to-install-haskell-packages">How to
+      install Haskell packages</link> how you can install those programs
+      into your user profile:
+    </para>
+    <programlisting>
+$ nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA haskellPackages.ghc haskellPackages.cabal-install
+</programlisting>
+    <para>
+      Instead of the default package set
+      <literal>haskellPackages</literal>, you can also use the more
+      precise name <literal>haskell.compiler.ghc7101</literal>, which
+      has the advantage that it refers to the same GHC version
+      regardless of what Nixpkgs considers &quot;default&quot; at any
+      given time.
+    </para>
+    <para>
+      Once you've made those tools available in
+      <literal>$PATH</literal>, it's possible to build Hackage packages
+      the same way people without access to Nix do it all the time:
+    </para>
+    <programlisting>
+$ cabal get lens-4.11 &amp;&amp; cd lens-4.11
+$ cabal install -j --dependencies-only
+$ cabal configure
+$ cabal build
+</programlisting>
+    <para>
+      If you enjoy working with Cabal sandboxes, then that's entirely
+      possible too: just execute the command
+    </para>
+    <programlisting>
+$ cabal sandbox init
+</programlisting>
+    <para>
+      before installing the required dependencies.
+    </para>
+    <para>
+      The <literal>nix-shell</literal> utility makes it easy to switch
+      to a different compiler version; just enter the Nix shell
+      environment with the command
+    </para>
+    <programlisting>
+$ nix-shell -p haskell.compiler.ghc784
+</programlisting>
+    <para>
+      to bring GHC 7.8.4 into <literal>$PATH</literal>. Re-running
+      <literal>cabal configure</literal> switches your build to use that
+      compiler instead. If you're working on a project that doesn't
+      depend on any additional system libraries outside of GHC, then
+      it's sufficient even to run the <literal>cabal configure</literal>
+      command inside of the shell:
+    </para>
+    <programlisting>
+$ nix-shell -p haskell.compiler.ghc784 --command &quot;cabal configure&quot;
+</programlisting>
+    <para>
+      Afterwards, all other commands like <literal>cabal build</literal>
+      work just fine in any shell environment, because the configure
+      phase recorded the absolute paths to all required tools like GHC
+      in its build configuration inside of the <literal>dist/</literal>
+      directory. Please note, however, that
+      <literal>nix-collect-garbage</literal> can break such an
+      environment because the Nix store paths created by
+      <literal>nix-shell</literal> aren't &quot;alive&quot; anymore once
+      <literal>nix-shell</literal> has terminated. If you find that your
+      Haskell builds no longer work after garbage collection, then
+      you'll have to re-run <literal>cabal configure</literal> inside of
+      a new <literal>nix-shell</literal> environment.
+    </para>
+  </section>
+  <section xml:id="how-to-install-a-compiler-with-libraries">
+    <title>How to install a compiler with libraries</title>
+    <para>
+      GHC expects to find all installed libraries inside of its own
+      <literal>lib</literal> directory. This approach works fine on
+      traditional Unix systems, but it doesn't work for Nix, because
+      GHC's store path is immutable once it's built. We cannot install
+      additional libraries into that location. As a consequence, our
+      copies of GHC don't know any packages except their own core
+      libraries, like <literal>base</literal>,
+      <literal>containers</literal>, <literal>Cabal</literal>, etc.
+    </para>
+    <para>
+      We can register additional libraries to GHC, however, using a
+      special build function called <literal>ghcWithPackages</literal>.
+      That function expects one argument: a function that maps from an
+      attribute set of Haskell packages to a list of packages, which
+      determines the libraries known to that particular version of GHC.
+      For example, the Nix expression
+      <literal>ghcWithPackages (pkgs: [pkgs.mtl])</literal> generates a
+      copy of GHC that has the <literal>mtl</literal> library registered
+      in addition to its normal core packages:
+    </para>
+    <programlisting>
+$ nix-shell -p &quot;haskellPackages.ghcWithPackages (pkgs: [pkgs.mtl])&quot;
+
+[nix-shell:~]$ ghc-pkg list mtl
+/nix/store/zy79...-ghc-7.10.1/lib/ghc-7.10.1/package.conf.d:
+    mtl-2.2.1
+</programlisting>
+    <para>
+      This function allows users to define their own development
+      environment by means of an override. After adding the following
+      snippet to <literal>~/.nixpkgs/config.nix</literal>,
+    </para>
+    <programlisting>
+{
+  packageOverrides = super: let self = super.pkgs; in
+  {
+    myHaskellEnv = self.haskell.packages.ghc7101.ghcWithPackages
+                     (haskellPackages: with haskellPackages; [
+                       # libraries
+                       arrows async cgi criterion
+                       # tools
+                       cabal-install haskintex
+                     ]);
+  };
+}
+</programlisting>
+    <para>
+      it's possible to install that compiler with
+      <literal>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA myHaskellEnv</literal>.
+      If you'd like to switch that development environment to a
+      different version of GHC, just replace the
+      <literal>ghc7101</literal> bit in the previous definition with the
+      appropriate name. Of course, it's also possible to define any
+      number of these development environments! (You can't install two
+      of them into the same profile at the same time, though, because
+      that would result in file conflicts.)
+    </para>
+    <para>
+      The generated <literal>ghc</literal> program is a wrapper script
+      that re-directs the real GHC executable to use a new
+      <literal>lib</literal> directory --- one that we specifically
+      constructed to contain all those packages the user requested:
+    </para>
+    <programlisting>
+$ cat $(type -p ghc)
+#! /nix/store/xlxj...-bash-4.3-p33/bin/bash -e
+export NIX_GHC=/nix/store/19sm...-ghc-7.10.1/bin/ghc
+export NIX_GHCPKG=/nix/store/19sm...-ghc-7.10.1/bin/ghc-pkg
+export NIX_GHC_DOCDIR=/nix/store/19sm...-ghc-7.10.1/share/doc/ghc/html
+export NIX_GHC_LIBDIR=/nix/store/19sm...-ghc-7.10.1/lib/ghc-7.10.1
+exec /nix/store/j50p...-ghc-7.10.1/bin/ghc &quot;-B$NIX_GHC_LIBDIR&quot; &quot;$@&quot;
+</programlisting>
+    <para>
+      The variables <literal>$NIX_GHC</literal>,
+      <literal>$NIX_GHCPKG</literal>, etc. point to the
+      <emphasis>new</emphasis> store path
+      <literal>ghcWithPackages</literal> constructed specifically for
+      this environment. The last line of the wrapper script then
+      executes the real <literal>ghc</literal>, but passes the path to
+      the new <literal>lib</literal> directory using GHC's
+      <literal>-B</literal> flag.
+    </para>
+    <para>
+      The purpose of those environment variables is to work around an
+      impurity in the popular
+      <link xlink:href="http://hackage.haskell.org/package/ghc-paths">ghc-paths</link>
+      library. That library promises to give its users access to GHC's
+      installation paths. Only, the library can't possible know that
+      path when it's compiled, because the path GHC considers its own is
+      determined only much later, when the user configures it through
+      <literal>ghcWithPackages</literal>. So we
+      <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/haskell-modules/ghc-paths-nix.patch">patched
+      ghc-paths</link> to return the paths found in those environment
+      variables at run-time rather than trying to guess them at
+      compile-time.
+    </para>
+    <para>
+      To make sure that mechanism works properly all the time, we
+      recommend that you set those variables to meaningful values in
+      your shell environment, too, i.e. by adding the following code to
+      your <literal>~/.bashrc</literal>:
+    </para>
+    <programlisting>
+if type &gt;/dev/null 2&gt;&amp;1 -p ghc; then
+  eval &quot;$(egrep ^export &quot;$(type -p ghc)&quot;)&quot;
+fi
+</programlisting>
+    <para>
+      If you are certain that you'll use only one GHC environment which
+      is located in your user profile, then you can use the following
+      code, too, which has the advantage that it doesn't contain any
+      paths from the Nix store, i.e. those settings always remain valid
+      even if a <literal>nix-env -u</literal> operation updates the GHC
+      environment in your profile:
+    </para>
+    <programlisting>
+if [ -e ~/.nix-profile/bin/ghc ]; then
+  export NIX_GHC=&quot;$HOME/.nix-profile/bin/ghc&quot;
+  export NIX_GHCPKG=&quot;$HOME/.nix-profile/bin/ghc-pkg&quot;
+  export NIX_GHC_DOCDIR=&quot;$HOME/.nix-profile/share/doc/ghc/html&quot;
+  export NIX_GHC_LIBDIR=&quot;$HOME/.nix-profile/lib/ghc-$($NIX_GHC --numeric-version)&quot;
+fi
+</programlisting>
+  </section>
+  <section xml:id="how-to-create-ad-hoc-environments-for-nix-shell">
+    <title>How to create ad hoc environments for
+    <literal>nix-shell</literal></title>
+    <para>
+      The easiest way to create an ad hoc development environment is to
+      run <literal>nix-shell</literal> with the appropriate GHC
+      environment given on the command-line:
+    </para>
+    <programlisting>
+nix-shell -p &quot;haskellPackages.ghcWithPackages (pkgs: with pkgs; [mtl pandoc])&quot;
+</programlisting>
+    <para>
+      For more sophisticated use-cases, however, it's more convenient to
+      save the desired configuration in a file called
+      <literal>shell.nix</literal> that looks like this:
+    </para>
+    <programlisting>
+{ nixpkgs ? import &lt;nixpkgs&gt; {}, compiler ? &quot;ghc7101&quot; }:
+let
+  inherit (nixpkgs) pkgs;
+  ghc = pkgs.haskell.packages.${compiler}.ghcWithPackages (ps: with ps; [
+          monad-par mtl
+        ]);
+in
+pkgs.stdenv.mkDerivation {
+  name = &quot;my-haskell-env-0&quot;;
+  buildInputs = [ ghc ];
+  shellHook = &quot;eval $(egrep ^export ${ghc}/bin/ghc)&quot;;
+}
+</programlisting>
+    <para>
+      Now run <literal>nix-shell</literal> --- or even
+      <literal>nix-shell --pure</literal> --- to enter a shell
+      environment that has the appropriate compiler in
+      <literal>$PATH</literal>. If you use <literal>--pure</literal>,
+      then add all other packages that your development environment
+      needs into the <literal>buildInputs</literal> attribute. If you'd
+      like to switch to a different compiler version, then pass an
+      appropriate <literal>compiler</literal> argument to the
+      expression, i.e.
+      <literal>nix-shell --argstr compiler ghc784</literal>.
+    </para>
+    <para>
+      If you need such an environment because you'd like to compile a
+      Hackage package outside of Nix --- i.e. because you're hacking on
+      the latest version from Git ---, then the package set provides
+      suitable nix-shell environments for you already! Every Haskell
+      package has an <literal>env</literal> attribute that provides a
+      shell environment suitable for compiling that particular package.
+      If you'd like to hack the <literal>lens</literal> library, for
+      example, then you just have to check out the source code and enter
+      the appropriate environment:
+    </para>
+    <programlisting>
+  $ cabal get lens-4.11 &amp;&amp; cd lens-4.11
+  Downloading lens-4.11...
+  Unpacking to lens-4.11/
+
+  $ nix-shell &quot;&lt;nixpkgs&gt;&quot; -A haskellPackages.lens.env
+  [nix-shell:/tmp/lens-4.11]$
+</programlisting>
+    <para>
+      At point, you can run <literal>cabal configure</literal>,
+      <literal>cabal build</literal>, and all the other development
+      commands. Note that you need <literal>cabal-install</literal>
+      installed in your <literal>$PATH</literal> already to use it here
+      --- the <literal>nix-shell</literal> environment does not provide
+      it.
+    </para>
+  </section>
+</section>
+<section xml:id="how-to-create-nix-builds-for-your-own-private-haskell-packages">
+  <title>How to create Nix builds for your own private Haskell
+  packages</title>
+  <para>
+    If your own Haskell packages have build instructions for Cabal, then
+    you can convert those automatically into build instructions for Nix
+    using the <literal>cabal2nix</literal> utility, which you can
+    install into your profile by running
+    <literal>nix-env -i cabal2nix</literal>.
+  </para>
+  <section xml:id="how-to-build-a-stand-alone-project">
+    <title>How to build a stand-alone project</title>
+    <para>
+      For example, let's assume that you're working on a private project
+      called <literal>foo</literal>. To generate a Nix build expression
+      for it, change into the project's top-level directory and run the
+      command:
+    </para>
+    <programlisting>
+$ cabal2nix . &gt;foo.nix
+</programlisting>
+    <para>
+      Then write the following snippet into a file called
+      <literal>default.nix</literal>:
+    </para>
+    <programlisting>
+{ nixpkgs ? import &lt;nixpkgs&gt; {}, compiler ? &quot;ghc7101&quot; }:
+nixpkgs.pkgs.haskell.packages.${compiler}.callPackage ./foo.nix { }
+</programlisting>
+    <para>
+      Finally, store the following code in a file called
+      <literal>shell.nix</literal>:
+    </para>
+    <programlisting>
+{ nixpkgs ? import &lt;nixpkgs&gt; {}, compiler ? &quot;ghc7101&quot; }:
+(import ./default.nix { inherit nixpkgs compiler; }).env
+</programlisting>
+    <para>
+      At this point, you can run <literal>nix-build</literal> to have
+      Nix compile your project and install it into a Nix store path. The
+      local directory will contain a symlink called
+      <literal>result</literal> after <literal>nix-build</literal>
+      returns that points into that location. Of course, passing the
+      flag <literal>--argstr compiler ghc763</literal> allows switching
+      the build to any version of GHC currently supported.
+    </para>
+    <para>
+      Furthermore, you can call <literal>nix-shell</literal> to enter an
+      interactive development environment in which you can use
+      <literal>cabal configure</literal> and
+      <literal>cabal build</literal> to develop your code. That
+      environment will automatically contain a proper GHC derivation
+      with all the required libraries registered as well as all the
+      system-level libraries your package might need.
+    </para>
+    <para>
+      If your package does not depend on any system-level libraries,
+      then it's sufficient to run
+    </para>
+    <programlisting>
+$ nix-shell --command &quot;cabal configure&quot;
+</programlisting>
+    <para>
+      once to set up your build. <literal>cabal-install</literal>
+      determines the absolute paths to all resources required for the
+      build and writes them into a config file in the
+      <literal>dist/</literal> directory. Once that's done, you can run
+      <literal>cabal build</literal> and any other command for that
+      project even outside of the <literal>nix-shell</literal>
+      environment. This feature is particularly nice for those of us who
+      like to edit their code with an IDE, like Emacs'
+      <literal>haskell-mode</literal>, because it's not necessary to
+      start Emacs inside of nix-shell just to make it find out the
+      necessary settings for building the project;
+      <literal>cabal-install</literal> has already done that for us.
+    </para>
+    <para>
+      If you want to do some quick-and-dirty hacking and don't want to
+      bother setting up a <literal>default.nix</literal> and
+      <literal>shell.nix</literal> file manually, then you can use the
+      <literal>--shell</literal> flag offered by
+      <literal>cabal2nix</literal> to have it generate a stand-alone
+      <literal>nix-shell</literal> environment for you. With that
+      feature, running
+    </para>
+    <programlisting>
+$ cabal2nix --shell . &gt;shell.nix
+$ nix-shell --command &quot;cabal configure&quot;
+</programlisting>
+    <para>
+      is usually enough to set up a build environment for any given
+      Haskell package. You can even use that generated file to run
+      <literal>nix-build</literal>, too:
+    </para>
+    <programlisting>
+$ nix-build shell.nix
+</programlisting>
+  </section>
+  <section xml:id="how-to-build-projects-that-depend-on-each-other">
+    <title>How to build projects that depend on each other</title>
+    <para>
+      If you have multiple private Haskell packages that depend on each
+      other, then you'll have to register those packages in the Nixpkgs
+      set to make them visible for the dependency resolution performed
+      by <literal>callPackage</literal>. First of all, change into each
+      of your projects top-level directories and generate a
+      <literal>default.nix</literal> file with
+      <literal>cabal2nix</literal>:
+    </para>
+    <programlisting>
+$ cd ~/src/foo &amp;&amp; cabal2nix . &gt;default.nix
+$ cd ~/src/bar &amp;&amp; cabal2nix . &gt;default.nix
+</programlisting>
+    <para>
+      Then edit your <literal>~/.nixpkgs/config.nix</literal> file to
+      register those builds in the default Haskell package set:
+    </para>
+    <programlisting>
+  {
+    packageOverrides = super: let self = super.pkgs; in
+    {
+      haskellPackages = super.haskellPackages.override {
+        overrides = self: super: {
+          foo = self.callPackage ../src/foo {};
+          bar = self.callPackage ../src/bar {};
+        };
+      };
+    };
+  }
+</programlisting>
+    <para>
+      Once that's accomplished,
+      <literal>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -qA haskellPackages</literal>
+      will show your packages like any other package from Hackage, and
+      you can build them
+    </para>
+    <programlisting>
+$ nix-build &quot;&lt;nixpkgs&gt;&quot; -A haskellPackages.foo
+</programlisting>
+    <para>
+      or enter an interactive shell environment suitable for building
+      them:
+    </para>
+    <programlisting>
+$ nix-shell &quot;&lt;nixpkgs&gt;&quot; -A haskellPackages.bar.env
+</programlisting>
+  </section>
+</section>
+<section xml:id="miscellaneous-topics">
+  <title>Miscellaneous Topics</title>
+  <section xml:id="how-to-build-with-profiling-enabled">
+    <title>How to build with profiling enabled</title>
+    <para>
+      Every Haskell package set takes a function called
+      <literal>overrides</literal> that you can use to manipulate the
+      package as much as you please. One useful application of this
+      feature is to replace the default <literal>mkDerivation</literal>
+      function with one that enables library profiling for all packages.
+      To accomplish that, add configure the following snippet in your
+      <literal>~/.nixpkgs/config.nix</literal> file:
+    </para>
+    <programlisting>
+{
+  packageOverrides = super: let self = super.pkgs; in
+  {
+    profiledHaskellPackages = self.haskellPackages.override {
+      overrides = self: super: {
+        mkDerivation = args: super.mkDerivation (args // {
+          enableLibraryProfiling = true;
+        });
+      };
+    };
+  };
+}
+</programlisting>
+  </section>
+  <section xml:id="how-to-override-package-versions-in-a-compiler-specific-package-set">
+    <title>How to override package versions in a compiler-specific
+    package set</title>
+    <para>
+      Nixpkgs provides the latest version of
+      <link xlink:href="http://hackage.haskell.org/package/ghc-events"><literal>ghc-events</literal></link>,
+      which is 0.4.4.0 at the time of this writing. This is fine for
+      users of GHC 7.10.x, but GHC 7.8.4 cannot compile that binary.
+      Now, one way to solve that problem is to register an older version
+      of <literal>ghc-events</literal> in the 7.8.x-specific package
+      set. The first step is to generate Nix build instructions with
+      <literal>cabal2nix</literal>:
+    </para>
+    <programlisting>
+$ cabal2nix cabal://ghc-events-0.4.3.0 &gt;~/.nixpkgs/ghc-events-0.4.3.0.nix
+</programlisting>
+    <para>
+      Then add the override in <literal>~/.nixpkgs/config.nix</literal>:
+    </para>
+    <programlisting>
+{
+  packageOverrides = super: let self = super.pkgs; in
+  {
+    haskell = super.haskell // {
+      packages = super.haskell.packages // {
+        ghc784 = super.haskell.packages.ghc784.override {
+          overrides = self: super: {
+            ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
+          };
+        };
+      };
+    };
+  };
+}
+</programlisting>
+    <para>
+      This code is a little crazy, no doubt, but it's necessary because
+      the intuitive version
+    </para>
+    <programlisting>
+haskell.packages.ghc784 = super.haskell.packages.ghc784.override {
+  overrides = self: super: {
+    ghc-events = self.callPackage ./ghc-events-0.4.3.0.nix {};
+  };
+};
+</programlisting>
+    <para>
+      doesn't do what we want it to: that code replaces the
+      <literal>haskell</literal> package set in Nixpkgs with one that
+      contains only one entry,<literal>packages</literal>, which
+      contains only one entry <literal>ghc784</literal>. This override
+      loses the <literal>haskell.compiler</literal> set, and it loses
+      the <literal>haskell.packages.ghcXYZ</literal> sets for all
+      compilers but GHC 7.8.4. To avoid that problem, we have to perform
+      the convoluted little dance from above, iterating over each step
+      in hierarchy.
+    </para>
+    <para>
+      Once it's accomplished, however, we can install a variant of
+      <literal>ghc-events</literal> that's compiled with GHC 7.8.4:
+    </para>
+    <programlisting>
+nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA haskell.packages.ghc784.ghc-events
+</programlisting>
+    <para>
+      Unfortunately, it turns out that this build fails again while
+      executing the test suite! Apparently, the release archive on
+      Hackage is missing some data files that the test suite requires,
+      so we cannot run it. We accomplish that by re-generating the Nix
+      expression with the <literal>--no-check</literal> flag:
+    </para>
+    <programlisting>
+$ cabal2nix --no-check cabal://ghc-events-0.4.3.0 &gt;~/.nixpkgs/ghc-events-0.4.3.0.nix
+</programlisting>
+    <para>
+      Now the builds succeeds.
+    </para>
+    <para>
+      Of course, in the concrete example of
+      <literal>ghc-events</literal> this whole exercise is not an ideal
+      solution, because <literal>ghc-events</literal> can analyze the
+      output emitted by any version of GHC later than 6.12 regardless of
+      the compiler version that was used to build the `ghc-events'
+      executable, so strictly speaking there's no reason to prefer one
+      built with GHC 7.8.x in the first place. However, for users who
+      cannot use GHC 7.10.x at all for some reason, the approach of
+      downgrading to an older version might be useful.
+    </para>
+  </section>
+  <section xml:id="how-to-recover-from-ghcs-infamous-non-deterministic-library-id-bug">
+    <title>How to recover from GHC's infamous non-deterministic library
+    ID bug</title>
+    <para>
+      GHC and distributed build farms don't get along well:
+    </para>
+    <programlisting>
+https://ghc.haskell.org/trac/ghc/ticket/4012
+</programlisting>
+    <para>
+      When you see an error like this one
+    </para>
+    <programlisting>
+package foo-0.7.1.0 is broken due to missing package
+text-1.2.0.4-98506efb1b9ada233bb5c2b2db516d91
+</programlisting>
+    <para>
+      then you have to download and re-install <literal>foo</literal>
+      and all its dependents from scratch:
+    </para>
+    <programlisting>
+# nix-store -q --referrers /nix/store/*-haskell-text-1.2.0.4 \
+  | nix-store --repair-path --option binary-caches http://hydra.nixos.org
+</programlisting>
+    <para>
+      If you're using additional Hydra servers other than
+      <literal>hydra.nixos.org</literal>, then it might be necessary to
+      purge the local caches that store data from those machines to
+      disable these binary channels for the duration of the previous
+      command, i.e. by running:
+    </para>
+    <programlisting>
+rm /nix/var/nix/binary-cache-v3.sqlite
+rm /nix/var/nix/manifests/*
+rm /nix/var/nix/channel-cache/*
+</programlisting>
+  </section>
+  <section xml:id="builds-on-darwin-fail-with-math.h-not-found">
+    <title>Builds on Darwin fail with <literal>math.h</literal> not
+    found</title>
+    <para>
+      Users of GHC on Darwin have occasionally reported that builds
+      fail, because the compiler complains about a missing include file:
+    </para>
+    <programlisting>
+fatal error: 'math.h' file not found
+</programlisting>
+    <para>
+      The issue has been discussed at length in
+      <link xlink:href="https://github.com/NixOS/nixpkgs/issues/6390">ticket
+      6390</link>, and so far no good solution has been proposed. As a
+      work-around, users who run into this problem can configure the
+      environment variables
+    </para>
+    <programlisting>
+export NIX_CFLAGS_COMPILE=&quot;-idirafter /usr/include&quot;
+export NIX_CFLAGS_LINK=&quot;-L/usr/lib&quot;
+</programlisting>
+    <para>
+      in their <literal>~/.bashrc</literal> file to avoid the compiler
+      error.
+    </para>
+  </section>
+</section>
+
+</chapter>
diff --git a/doc/manual.xml b/doc/manual.xml
index 1b713b0c30c..a6400c98d6e 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -18,5 +18,6 @@
   <xi:include href="package-notes.xml" />
   <xi:include href="coding-conventions.xml" />
   <xi:include href="contributing.xml" />
+  <xi:include href="haskell-users-guide.xml" />
 
 </book>