@@ -1,34 +1,96 @@
1−% User's Guide for Haskell in Nixpkgs
2−% Peter Simons \<simons@cryp.to\>
3−% 2015-05-21
4−
5−# Install Haskell packages from Hackage
6−
7−Lookups based on package names like
8−
9− $ nix-env -i cabal-install
10−
11−don't work! You have to use attribute paths:
12−
13− $ nix-env -iA haskellPackages.cabal-install
14−
15−To list all Haskell packages, run:
16−
17− $ nix-env -qaP -A haskellPackages
18−
19−There is one Haskell package set per compiler:
20−
21− $ nix-env -qaP -A haskellPackages
22− $ nix-env -qaP -A haskell.packages.ghc6123
23− $ nix-env -qaP -A haskell.packages.ghc763
24− $ nix-env -qaP -A haskell.packages.ghc7101
25−
26−The default `haskellPackages` currently refers to
27−`haskell.packages.ghc7101`.
28−
29− $ nix-env -iA haskell.compiler.ghc784
30−
31− $ nix-env -qaP -A haskell.compiler
1+---
2+title: User's Guide for Haskell in Nixpkgs
3+author: Peter Simons \<simons@cryp.to\>
4+date: 2015-05-21
5+---
6+
7+# How to install Haskell packages
8+
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:
12+
13+ $ nix-env -qa cabal-install
14+ error: selector ‘cabal-install’ matches no derivations
15+
16+ $ nix-env -i ghc
17+ error: selector ‘ghc’ matches no derivations
18+
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:
24+
25+ $ nix-env -f "<nixpkgs>" -qaP -A haskellPackages
26+ haskellPackages.a50 a50-0.5
27+ haskellPackages.abacate haskell-abacate-0.0.0.0
28+ haskellPackages.abcBridge haskell-abcBridge-0.12
29+ haskellPackages.afv afv-0.1.1
30+ haskellPackages.alex alex-3.1.4
31+ haskellPackages.Allure Allure-0.4.101.1
32+ haskellPackages.alms alms-0.6.7
33+ [... some 8000 entries omitted ...]
34+
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):
45+
46+ $ nix-env -f "<nixpkgs>" -iA haskellPackages.Allure ...
47+
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
50+`haskellPackages.cabal-install`, and so
51+on.[^names-that-cannot-be-mapped-to-attributes]
52+
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:
57+
58+ $ nix-env -iA haskellPackages.cabal-install --dry-run
59+ error: attribute ‘haskellPackages’ in selection path
60+ ‘haskellPackages.cabal-install’ not found
61+
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.:
67+
68+ $ nix-env -qaP coreutils
69+ nixos.pkgs.coreutils coreutils-8.23
70+
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:
74+
75+ $ nix-env -qaP -A nixos.pkgs.haskellPackages
76+ $ nix-env -iA nixos.pkgs.haskellPackages.cabal-install
77+
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:
83+
84+ $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc6123
85+ $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc763
86+ $ nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc7101
87+
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:
92+
93+ $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler
3294 haskell.compiler.ghc6104 ghc-6.10.4
3395 haskell.compiler.ghc6123 ghc-6.12.3
3496 haskell.compiler.ghc704 ghc-7.0.4
@@ -42,15 +104,8 @@ The default `haskellPackages` currently refers to
42104 haskell.compiler.jhc jhc-0.8.2
43105 haskell.compiler.uhc uhc-1.1.9.0
44106
45−For every compiler version XYZ, the attributes
46−
47− haskell.compiler.ghcXYC
48−
49−and
50−
51− haskell.packages.ghcXYC.ghc
52−
53−are synonymous.
107+For every compiler version *XYZ*, the attributes `haskell.compiler.ghcXYC` and
108+`haskell.packages.ghcXYC.ghc` are synonymous.
54109
55110## Install more than one Haskell compiler
56111
@@ -67,8 +122,8 @@ are synonymous.
67122
68123### transient
69124
70− $ nix-env -p ~/ghc-7.6.3 -iA haskell.compiler.ghc763
71− $ nix-env -p ~/ghc-7.8.4 -iA haskell.compiler.ghc784
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
72127 [...]
73128
74129 $ export PATH=$HOME/ghc-7.6.3/bin:$PATH
@@ -80,7 +135,7 @@ are synonymous.
80135### permanent
81136
82137 $ PROFILE_DIR=/nix/var/nix/profiles/per-user/$USER
83− $ nix-env -p $PROFILE_DIR/ghc-7.6.3 -iA ...
138+ $ nix-env -f "<nixpkgs>" -p $PROFILE_DIR/ghc-7.6.3 -iA ...
84139
85140On NixOS, `/etc/profile` defines `$NIX_USER_PROFILE_DIR` automatically.
86141
@@ -100,7 +155,7 @@ Edit the file `~/.nixpkgs/config.nix`:
100155 };
101156 }
102157
103−Now installl with `nix-env -iA myHaskellEnv`.
158+Now installl with `nix-env -f "<nixpkgs>" -iA myHaskellEnv`.
104159
105160The generated `ghc` program is a wrapper script that re-directs the real
106161`ghc` to use a "libdir" with all the specified packages installed:
@@ -179,7 +234,7 @@ shell environment in which that package can be built:
179234
180235## For `nix-shell`
181236
182− $ nix-env -iA cabal2nix
237+ $ nix-env -f "<nixpkgs>" -iA cabal2nix
183238
184239 $ cabal2nix --shell . >shell.nix
185240 $ nix-shell --command "cabal configure"
@@ -215,7 +270,7 @@ Now edit `~/.nixpkgs/config.nix`:
215270 };
216271 }
217272
218−Build it by running "`nix-env -iA foo`".
273+Build it by running "`nix-env -f "<nixpkgs>" -iA foo`".
219274
220275## For `nix-build`
221276
@@ -248,7 +303,7 @@ Everyone else adds this setting to `/etc/nix/nix.conf`:
248303
249304 trusted-binary-caches = http://hydra.nixos.org
250305
251−Now run `nix-env`, `nix-build`, and `nix-shell` with this option:
306+Now run `nix-env -f "<nixpkgs>"`, `nix-build`, and `nix-shell` with this option:
252307
253308 --option extra-binary-caches http://hydra.nixos.org
254309
@@ -274,3 +329,13 @@ might be necessary to disable the binary channels for the duration of
274329the previous command, i.e. by running:
275330
276331 # nix-channel --remove nixos
332+
333+
334+
335+
336+[^Hackage]: http://http://hackage.haskell.org/
337+
338+[^names-that-cannot-be-mapped-to-attributes]: This convention causes trouble
339+with packages like `3dmodels` and `4Blocks`, because these names are invalid
340+identifiers in the Nix language. The issue of how to deal with these (rare)
341+corner cases is currently unresolved.