@@ -0,0 +1,143 @@
1+How to maintain Haskell Packages in Nix
2+=======================================
3+
4+## Overview over the tool-chain
5+
6+There are two utilities, `cabal2nix` and `hackage4nix`, that automate
7+maintenance to a large extend. We intend to merge them into one program,
8+eventually, but the necessary re-factoring hasn't been done yet since
9+this is not a high priority.
10+
11+### Cabal2nix
12+
13+`cabal2nix` converts a single Cabal file into a single Nix build
14+expression. For example:
15+
16+ $ cabal2nix cabal://yesod-0.9.1
17+ { cabal, attoparsecText, blazeBuilder, blazeHtml, hamlet, httpTypes
18+ , monadControl, parsec, shakespeareCss, shakespeareJs, text, time
19+ , transformers, unixCompat, wai, waiExtra, warp, yesodAuth
20+ , yesodCore, yesodForm, yesodJson, yesodPersistent
21+ }:
22+
23+ cabal.mkDerivation (self: {
24+ pname = "yesod";
25+ version = "0.9.1";
26+ sha256 = "1ag3lca75lrriycbscspb5yyishacgxjx0rybc3x4z1dqnkn1r71";
27+ isLibrary = true;
28+ isExecutable = true;
29+ buildDepends = [
30+ attoparsecText blazeBuilder blazeHtml hamlet httpTypes monadControl
31+ parsec shakespeareCss shakespeareJs text time transformers
32+ unixCompat wai waiExtra warp yesodAuth yesodCore yesodForm
33+ yesodJson yesodPersistent
34+ ];
35+ meta = {
36+ homepage = "http://www.yesodweb.com/";
37+ description = "Creation of type-safe, RESTful web applications";
38+ license = self.stdenv.lib.licenses.bsd3;
39+ platforms = self.ghc.meta.platforms;
40+ };
41+ })
42+
43+Cabal files can be referred to using the magic URL
44+`cabal://NAME-VERSION`, which will automatically download the file from
45+Hackage. Alternatively, a direct `http://host/path/pkg.cabal` URL can be
46+provided, as well as a `file:///local/path/pkg.cabal` URI that doesn't
47+depend on network access. Run the utility with `--help` to see the
48+complete list of supported command line flags.
49+
50+To add a new package to Nix, the following steps need to be performed:
51+
52+ $ cd $NIXPKGS_ALL/pkgs/development/libraries/haskell
53+ $ mkdir foo
54+ $ cabal2nix cabal://foo-1.0 >foo/default.nix
55+
56+Then add an appropriate attribute to
57+`pkgs/top-level/haskell-packages.nix`, for example:
58+
59+ foo = callPackage ../development/libraries/haskell/foo {};
60+
61+### Hackage4nix
62+
63+The `hackage4nix` utility re-generates *all* expressions found in the
64+`nixpkgs` database in place. This is useful to ensure that all packages
65+have been generated with a recent version of the tool-chain.
66+Furthermore, `hackage4nix` adds default settings for the
67+`meta.maintainers` and `meta.platforms` attribute if these aren't
68+configured yet. Generally speaking, running
69+
70+ $ hackage4nix $NIXPKGS_ALL
71+
72+should be a *no-op* --- i.e. no files should change! If there are
73+changes, these indicate that a file has been modified manually, and then
74+these changes must be investigated to find out what is going on.
75+
76+Last but not least, `hackage4nix` generates a list of all updates
77+available from Hackage. (Run `cabal update` to make sure that your local
78+copy of the Hackage database is up-to-date!) For example:
79+
80+ $ hackage4nix $NIXPKGS_ALL
81+ The following updates are available:
82+
83+ WebBits-Html-1.0.1:
84+ cabal2nix cabal://WebBits-Html-1.0.2 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/WebBits-Html/default.nix
85+
86+ happstack-server-6.1.6:
87+ cabal2nix cabal://happstack-server-6.2.1 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/happstack/happstack-server.nix
88+ cabal2nix cabal://happstack-server-6.2.2 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/happstack/happstack-server.nix
89+
90+ primitive-0.3.1:
91+ cabal2nix cabal://primitive-0.4 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/primitive/default.nix
92+
93+ repa-2.1.1.5:
94+ cabal2nix cabal://repa-2.1.1.6 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/repa/default.nix
95+
96+ unix-compat-0.2.2.1:
97+ cabal2nix cabal://unix-compat-0.3 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/unix-compat/default.nix
98+
99+ vector-0.7.1:
100+ cabal2nix cabal://vector-0.8 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/vector/default.nix
101+
102+These updates can be performed automatically by running the `cabal2nix`
103+command given by `hackage4nix`. If there is more than one possible
104+update, then all of them will be shown. Note, however, that some updates
105+break compilation of other packages, because they depend on very
106+specific versions of their build inputs, so please be careful when
107+performing updates!
108+
109+## Current State of Affairs
110+
111+The tool-chain is stable. As of today, 2011-08-30, almost all Haskell
112+packages available in Nix have been generated automatically from their
113+Cabal files. The exceptions are:
114+
115+* "Bad packages" that cannot be generated automatically because there
116+ is no proper Cabal file for them, or because their builds are so
117+ complicated that the `cabal.nix` build doesn't suffice to do the
118+ trick. The list of bad packages is hard-coded into
119+ [`hackage4nix.hs`](https://github.com/haskell4nix/cabal2nix/blob/master/src/Hackage4Nix.hs),
120+ in the functions `badPackagePaths` and `patchedPackages`. Any
121+ package list in there is going to be ignored by `hackage4nix`.
122+
123+* "Patched packages" cannot be generated automatically, because their
124+ build instructions need patches that `cabal2nix` doesn't (yet) know
125+ about. There is a hard-coded list of patched packages in
126+ [`hackage4nix`](https://github.com/haskell4nix/cabal2nix/blob/master/src/Hackage4Nix.hs).
127+ Furthermore, all build expressions that define any of the attributes
128+
129+ (pre|post)Configure
130+ (pre|post)Install
131+ patchPhase
132+
133+ are considered "patched". That list of attributes is hard-coded in
134+ [`hackage4nix.hs`](https://github.com/haskell4nix/cabal2nix/blob/master/src/Hackage4Nix.hs)
135+ in the function `regenerateDerivation`.
136+
137+The complete list of Haskell packages available in Nix is generated by
138+the tool [`package-list`](https://github.com/haskell4nix/package-list),
139+and published at <http://cryp.to/haskell-in-nixpkgs.txt>. Hackage picks
140+it up from there and generates links on each package's homepage to the
141+corresponding page in Hydra automatically. See [ticket
142+875](http://hackage.haskell.org/trac/hackage/ticket/875) for further
143+details.