@@ -6,9 +6,9 @@ date: 2015-05-21
66
77# How to install Haskell packages
88
9−Nixpkgs distributes build instructions for all Haskell packages that are
10−registered on Hackage[^Hackage], but strangely enough those packages cannot be
11−discovered with the normal Nix package look-up:
9+Nixpkgs distributes build instructions for all Haskell packages registered on
10+Hackage[^Hackage], but strangely enough normal Nix package lookups don't seem
11+to discover any of them:
1212
1313 $ nix-env -qa cabal-install
1414 error: selector ‘cabal-install’ matches no derivations
@@ -16,11 +16,11 @@ discovered with the normal Nix package look-up:
1616 $ nix-env -i ghc
1717 error: selector ‘ghc’ matches no derivations
1818
19−The reason for this strange behavior is that the Haskell package set is *huge*,
20−and if all Haskell packages were visible in the top-level package set, then
21−those kind of name-based search/install operations would be slowed down a lot.
22−So, instead of that, we keep Haskell-related packages in a separate attribute
23−set called `haskellPackages` which can be listed by running:
19+The Haskell package set is not registered in the top-level namespace because it
20+is *huge*. If all Haskell packages were visible to these commands, then
21+name-based search/install operations would be much slower than they are now. We
22+avoided that by keeping all Haskell-related packages in a separate attribute
23+set called `haskellPackages`, which the following command will list:
2424
2525 $ nix-env -f "<nixpkgs>" -qaP -A haskellPackages
2626 haskellPackages.a50 a50-0.5
@@ -32,63 +32,63 @@ set called `haskellPackages` which can be listed by running:
3232 haskellPackages.alms alms-0.6.7
3333 [... some 8000 entries omitted ...]
3434
35−Haskell packages who's Nix name (second column) begins with a `haskell-` prefix
36−are packages that provide a library whereas packages without that prefix
37−provide just executables. (Libraries may provide executables too, though. The
38−package `haskell-pandoc`, for example, installs both a library and an
39−application.) You can install and use Haskell executables just like any other
40−program in Nixpkgs, but using Haskell libraries for development is a bit
41−trickier and we'll address that subject in great detail in the next section.
42−
43−To install any of those packages into your profile, refer to them by attribute
44−path (first column):
35+To install any of those packages into your profile, refer to them by their
36+attribute path (first column):
4537
4638 $ nix-env -f "<nixpkgs>" -iA haskellPackages.Allure ...
4739
48−The name of every Haskell packages' attribute corresponds exactly to the name
49−of the package on Hackage. The package `cabal-install` has the attribute
40+The attribute path of any Haskell packages corresponds to the name of that
41+particular package on Hackage: the package `cabal-install` has the attribute
5042`haskellPackages.cabal-install`, and so
5143on.[^names-that-cannot-be-mapped-to-attributes]
5244
53−Attribute paths may vary depending on they way your system is set up. We dodged
54−that problem so far by giving `nix-env` an explicit `-f "<nixpkgs>"` parameter,
55−but if you call `nix-env` without that flag, then chances are the invocation
56−fails:
45+Haskell packages who's Nix name (second column) begins with a `haskell-` prefix
46+are packages that provide a library whereas packages without that prefix
47+provide just executables. Libraries may provide executables too, though: the
48+package `haskell-pandoc`, for example, installs both a library and an
49+application. You can install and use Haskell executables just like any other
50+program in Nixpkgs, but using Haskell libraries for development is a bit
51+trickier and we'll address that subject in great detail in section [How to
52+create a development environment].
53+
54+Attribute paths are deterministic inside of Nixpkgs, but the path necessary to
55+reach Nixpkgs varies from system to system. We dodged that problem by giving
56+`nix-env` an explicit `-f "<nixpkgs>"` parameter, but if you call `nix-env`
57+without that flag, then chances are the invocation fails:
5758
58− $ nix-env -iA haskellPackages.cabal-install --dry-run
59+ $ nix-env -iA haskellPackages.cabal-install
5960 error: attribute ‘haskellPackages’ in selection path
6061 ‘haskellPackages.cabal-install’ not found
6162
62−The `-f "<nixpkgs>"` argument ensures that the top-level namespace visible to
63−`nix-env` is the Nixpkgs package set. Without that parameter, however, this is
64−not necessarily the case. On NixOS, for example, Nixpkgs does by default *not*
65−live in the top-level namespace. The easiest way to figure out the proper
66−attribute path is to query for the path of a well-known Nixpkgs package, i.e.:
63+On NixOS, for example, Nixpkgs does *not* exist in the top-level namespace by
64+default. To figure out the proper attribute path, it's easiest to query for the
65+path of a well-known Nixpkgs package, i.e.:
6766
6867 $ nix-env -qaP coreutils
6968 nixos.pkgs.coreutils coreutils-8.23
7069
71−If your system responds like that (which most NixOS installatios will), then
72−the attribute path to `haskellPackages` is `nixos.pkgs.haskellPackages`, and
73−it's also possible to run `nix-env` as follows, ommitting the `-f` flag:
70+If your system responds like that (most NixOS installatios will), then the
71+attribute path to `haskellPackages` is `nixos.pkgs.haskellPackages`. Thus, if
72+you want to use `nix-env` without giving an explicit `-f` flag, then that's the
73+way to do it:
7474
7575 $ nix-env -qaP -A nixos.pkgs.haskellPackages
7676 $ nix-env -iA nixos.pkgs.haskellPackages.cabal-install
7777
78−## Choosing packages built with different compilers
79−
80−Nixpkgs contains the latest major release of every GHC since 6.10.4, and
81−consequently there is not just one Haskell package set --- there is one per
82−compiler:
78+Our current default compiler is GHC 7.10.x and the `haskellPackages` set
79+contains packages built with that particular version. Nixpkgs contains the
80+latest major release of every GHC since 6.10.4, however, and there is a whole
81+family of package sets available that defines Hackage packages built with each
82+of those compilers, too:
8383
8484 $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc6123
8585 $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc763
86− $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc7101
8786
88−The name `haskellPackages` is just a synonym for `haskell.packages.ghc7101`,
89−which is our recommended default package set at the moment, but ultimately you
90−are free to compile your Haskell packages with any GHC version you please. Run
91−the following command to display the complete list of available compilers:
87+The name `haskellPackages` is really just a synonym for
88+`haskell.packages.ghc7101`, because we prefer that package set internally and
89+recommend it to our users as their default choice, but ultimately you are free
90+to compile your Haskell packages with any GHC version you please. The following
91+command displays the complete list of available compilers:
9292
9393 $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler
9494 haskell.compiler.ghc6104 ghc-6.10.4
@@ -104,56 +104,80 @@ the following command to display the complete list of available compilers:
104104 haskell.compiler.jhc jhc-0.8.2
105105 haskell.compiler.uhc uhc-1.1.9.0
106106
107−For every compiler version *XYZ*, the attributes `haskell.compiler.ghcXYC` and
108−`haskell.packages.ghcXYC.ghc` are synonymous.
107+There exists a package set for every GHC version in that list. There are no
108+package sets for `jhc`, `uhc`, or any other non-`ghc` Haskell compiler,
109+unfortunately, because no-one figured out how to build Cabal packages with them
110+yet. It's probably no big deal to accomplish, but someone has to do it. Also,
111+the attributes `haskell.compiler.ghcXYC` and `haskell.packages.ghcXYC.ghc` are
112+synonymous for the sake of convenience.
113+
114+# How to create a development environment
115+
116+## How to install a compiler
109117
110−## Install more than one Haskell compiler
118+A 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
120+you can install those programs into your user profile:
111121
112−### temporary
122+ $ nix-env -f "<nixpkgs>" -iA haskellPackages.ghc haskellPackages.cabal-install
113123
114− $ nix-shell -p haskell.compiler.ghc7101
115− [nix-shell:~]$ ghc --numeric-version
116− 7.10.1
117− [nix-shell:~]$ exit
124+Instead of the default package set `haskellPackages`, you can also use the more
125+precise name `haskell.compiler.ghc7101`, which has the advantage that it refers
126+to the same GHC version regardless of what Nixpkgs considers "default" at any
127+given time.
118128
119− $ nix-shell -p haskell.compiler.ghc784 \
120− --command "cabal configure"
129+Once you've made those tools available in `$PATH`, it's possible to build
130+Hackage 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
121135 $ cabal build
122136
123−### transient
137+If you enjoy working with Cabal sandboxes, then that's entirely possible too:
138+just execute the command
124139
125− $ nix-env -f "<nixpkgs>" -p ~/ghc-7.6.3 -iA haskell.compiler.ghc763
126− $ nix-env -f "<nixpkgs>" -p ~/ghc-7.8.4 -iA haskell.compiler.ghc784
127− [...]
140+ $ cabal sandbox init
128141
129− $ export PATH=$HOME/ghc-7.6.3/bin:$PATH
130− $ ghc --numeric-version
131− 7.6.3
142+before installing the required dependencies.
132143
133− $ cabal configure --with-compiler=$HOME/ghc-7.6.3/bin/ghc
144+The `nix-shell` utility makes it easy to switch to a different compiler
145+version; just enter the Nix shell environment with the command
134146
135−### permanent
147+ $ nix-shell -p haskell.compiler.ghc784
136148
137− $ PROFILE_DIR=/nix/var/nix/profiles/per-user/$USER
138− $ nix-env -f "<nixpkgs>" -p $PROFILE_DIR/ghc-7.6.3 -iA ...
149+to bring GHC 7.8.4 into `$PATH`. Re-running `cabal configure` switches your
150+build to use that compiler instead. If you're working on a project that doesn't
151+depend on any additional system libraries outside of GHC, then it's sufficient
152+even to run the `cabal configure` command inside of the shell:
139153
140−On NixOS, `/etc/profile` defines `$NIX_USER_PROFILE_DIR` automatically.
154+ $ nix-shell -p haskell.compiler.ghc784 --command "cabal configure"
141155
142−# Create a Haskell development environment
156+Afterwards, all other commands like `cabal build` work just fine in any shell
157+environment, because the configure phase recorded the absolute paths to all
158+required tools like GHC in its build configuration inside of the `dist/`
159+directory. Please note, however, that `nix-collect-garbage` can break such an
160+environment because the Nix store paths created by `nix-shell` aren't "alive"
161+anymore once `nix-shell` has terminated. If you find that your Haskell builds
162+no longer work after garbage collection, then you'll have to re-run `cabal
163+configure` inside of a new `nix-shell` environment.
164+
165+## How to install a compiler with libraries
143166
144167Edit the file `~/.nixpkgs/config.nix`:
145168
169+ {
170+ packageOverrides = super: let self = super.pkgs; in
146171 {
147− packageOverrides = super: let self = super.pkgs; in
148− {
149− myHaskellEnv =
150− self.haskell.packages.ghc7101.ghcWithPackages
151− (haskellPackages: with haskellPackages; [
152− arrows async cabal-install case-insensitive
153− cgi criterion hspec HStringTemplate
154− ]);
155− };
156− }
172+ myHaskellEnv = self.haskell.packages.ghc7101.ghcWithPackages
173+ (haskellPackages: with haskellPackages; [
174+ # libraries
175+ arrows async cgi criterion
176+ # tools
177+ cabal-install haskintex
178+ ]);
179+ };
180+ }
157181
158182Now installl with `nix-env -f "<nixpkgs>" -iA myHaskellEnv`.
159183