git.iko.soy/typeable/cabal2nix
on v1.41 help sign in
typeable/cabal2nix/README.md
144 lines 6.2 kB history raw
1How to maintain Haskell Packages in Nix
2=======================================
4## Overview over the tool-chain
6There are two utilities, `cabal2nix` and `hackage4nix`, that automate
7maintenance to a large extend. We intend to merge them into one program,
8eventually, but the necessary re-factoring hasn't been done yet since
9this is not a high priority.
11### Cabal2nix
13`cabal2nix` converts a single Cabal file into a single Nix build
14expression. For example:
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 }:
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 })
43Cabal files can be referred to using the magic URL
44`cabal://NAME-VERSION`, which will automatically download the file from
45Hackage. Alternatively, a direct `http://host/path/pkg.cabal` URL can be
46provided, as well as a `file:///local/path/pkg.cabal` URI that doesn't
47depend on network access. Run the utility with `--help` to see the
48complete list of supported command line flags.
50To add a new package to Nix, the following steps need to be performed:
52 $ cd $NIXPKGS_ALL/pkgs/development/libraries/haskell
53 $ mkdir foo
54 $ cabal2nix cabal://foo-1.0 >foo/default.nix
56Then add an appropriate attribute to
57`pkgs/top-level/haskell-packages.nix`, for example:
59 foo = callPackage ../development/libraries/haskell/foo {};
61### Hackage4nix
63The `hackage4nix` utility re-generates *all* expressions found in the
64`nixpkgs` database in place. This is useful to ensure that all packages
65have been generated with a recent version of the tool-chain.
66Furthermore, `hackage4nix` adds default settings for the
67`meta.maintainers` and `meta.platforms` attribute if these aren't
68configured yet. Generally speaking, running
70 $ hackage4nix $NIXPKGS_ALL
72should be a *no-op* --- i.e. no files should change! If there are
73changes, these indicate that a file has been modified manually, and then
74these changes must be investigated to find out what is going on.
76Last but not least, `hackage4nix` generates a list of all updates
77available from Hackage. (Run `cabal update` to make sure that your local
78copy of the Hackage database is up-to-date!) For example:
80 $ hackage4nix $NIXPKGS_ALL
81 The following updates are available:
83 WebBits-Html-1.0.1:
84 cabal2nix cabal://WebBits-Html-1.0.2 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/WebBits-Html/default.nix
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
90 primitive-0.3.1:
91 cabal2nix cabal://primitive-0.4 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/primitive/default.nix
93 repa-2.1.1.5:
94 cabal2nix cabal://repa-2.1.1.6 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/repa/default.nix
96 unix-compat-0.2.2.1:
97 cabal2nix cabal://unix-compat-0.3 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/unix-compat/default.nix
99 vector-0.7.1:
100 cabal2nix cabal://vector-0.8 >$NIXPKGS_ALL/pkgs/development/libraries/haskell/vector/default.nix
102These updates can be performed automatically by running the `cabal2nix`
103command given by `hackage4nix`. If there is more than one possible
104update, then all of them will be shown. Note, however, that some updates
105break compilation of other packages, because they depend on very
106specific versions of their build inputs, so please be careful when
107performing updates!
109## Current State of Affairs
111The tool-chain is stable. As of today, 2011-08-30, almost all Haskell
112packages available in Nix have been generated automatically from their
113Cabal files. The exceptions are:
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`](http://github.com/NixOS/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`.
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`](http://github.com/NixOS/cabal2nix/blob/master/src/Hackage4Nix.hs).
127 Furthermore, all build expressions that define any of the attributes
129 (pre|post)Configure
130 (pre|post)Install
131 patchPhase
132 patches
134 are considered "patched". That list of attributes is hard-coded in
135 [`hackage4nix.hs`](http://github.com/NixOS/cabal2nix/blob/master/src/Hackage4Nix.hs)
136 in the function `regenerateDerivation`.
138The complete list of Haskell packages available in Nix is generated by
139the tool [`package-list`](http://github.com/peti/package-list),
140and published at <http://cryp.to/haskell-in-nixpkgs.txt>. Hackage picks
141it up from there and generates links on each package's homepage to the
142corresponding page in Hydra automatically. See [ticket
143875](http://hackage.haskell.org/trac/hackage/ticket/875) for further
144details.