git.iko.soy/typeable/cabal2nix
on v1.50 help sign in
typeable/cabal2nix/README.md
135 lines 5.6 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, 2013-04-12, virtually all Haskell
112packages available in Nix have been generated automatically from their
113Cabal files. There are only a handful of exceptions, which we cannot
114generate because these packages aren't available on Hackage. The list of
115those packages is hard-coded into the
116[`hackage4nix.hs`](http://github.com/NixOS/cabal2nix/blob/master/src/Hackage4Nix.hs)
117binary in the function `badPackagePaths`.
119Furthermore, Hackage4Nix will not re-generate packages that have been
120patched, i.e. that define any of the following attributes:
122 (pre|post)Configure
123 (pre|post)Install
124 patchPhase
125 patches
127These packages are considered for updates, however.
129The complete list of Haskell packages available in Nix is generated by
130the tool [`package-list`](http://github.com/peti/package-list),
131and published at <http://cryp.to/haskell-in-nixpkgs.txt>. Hackage picks
132it up from there and generates links on each package's homepage to the
133corresponding page in Hydra automatically. See [ticket
134875](http://hackage.haskell.org/trac/hackage/ticket/875) for further
135details.