git.iko.soy/typeable/cabal2nix
on v1.59 help sign in
typeable/cabal2nix/README.md
137 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, checkout the Nixpkgs project from
51https://github.com/nixos/nixpkgs.git and run
53 $ cd pkgs/development/libraries/haskell
54 $ mkdir foo
55 $ cabal2nix cabal://foo-1.0 >foo/default.nix
57Then add an appropriate attribute to
58`pkgs/top-level/haskell-packages.nix`, for example:
60 foo = callPackage ../development/libraries/haskell/foo {};
62### Hackage4nix
64The `hackage4nix` utility re-generates *all* expressions found in the
65`nixpkgs` database in place. This is useful to ensure that all packages
66have been generated with a recent version of the tool-chain.
67Furthermore, `hackage4nix` adds default settings for the
68`meta.maintainers` and `meta.platforms` attribute if these aren't
69configured yet. Generally speaking, running
71 $ hackage4nix pkgs
73in your checked-out copy of the Nixpkgs tree should be a *no-op* ---
74i.e. no files should change! If there are changes, these indicate that a
75file has been modified manually, and then these changes must be
76investigated to find out what is going on.
78Last but not least, `hackage4nix` generates a list of all updates
79available from Hackage. (Run `cabal update` to make sure that your local
80copy of the Hackage database is up-to-date!) For example:
82 $ hackage4nix pkgs
83 The following updates are available:
85 WebBits-Html-1.0.1:
86 cabal2nix cabal://WebBits-Html-1.0.2 >pkgs/pkgs/development/libraries/haskell/WebBits-Html/default.nix
88 happstack-server-6.1.6:
89 cabal2nix cabal://happstack-server-6.2.1 >pkgs/pkgs/development/libraries/haskell/happstack/happstack-server.nix
90 cabal2nix cabal://happstack-server-6.2.2 >pkgs/pkgs/development/libraries/haskell/happstack/happstack-server.nix
92 primitive-0.3.1:
93 cabal2nix cabal://primitive-0.4 >pkgs/pkgs/development/libraries/haskell/primitive/default.nix
95 repa-2.1.1.5:
96 cabal2nix cabal://repa-2.1.1.6 >pkgs/pkgs/development/libraries/haskell/repa/default.nix
98 unix-compat-0.2.2.1:
99 cabal2nix cabal://unix-compat-0.3 >pkgs/pkgs/development/libraries/haskell/unix-compat/default.nix
101 vector-0.7.1:
102 cabal2nix cabal://vector-0.8 >pkgs/pkgs/development/libraries/haskell/vector/default.nix
104These updates can be performed automatically by running the `cabal2nix`
105command given by `hackage4nix`. If there is more than one possible
106update, then all of them will be shown. Note, however, that some updates
107break compilation of other packages, because they depend on very
108specific versions of their build inputs, so please be careful when
109performing updates!
111## Current State of Affairs
113The tool-chain is stable. As of today, 2013-04-12, virtually all Haskell
114packages available in Nix have been generated automatically from their
115Cabal files. There are only a handful of exceptions, which we cannot
116generate because these packages aren't available on Hackage. The list of
117those packages is hard-coded into the
118[`hackage4nix.hs`](https://github.com/NixOS/cabal2nix/blob/master/src/hackage4nix.hs)
119binary in the function `badPackagePaths`.
121Furthermore, Hackage4Nix will not re-generate packages that have been
122patched, i.e. that define any of the following attributes:
124 (pre|post)Configure
125 (pre|post)Install
126 patchPhase
127 patches
129These packages are considered for updates, however.
131The complete list of Haskell packages available in Nix is generated by
132the tool [`package-list`](http://github.com/peti/package-list),
133and published at <http://cryp.to/haskell-in-nixpkgs.txt>. Hackage picks
134it up from there and generates links on each package's homepage to the
135corresponding page in Hydra automatically. See [ticket
136875](http://www.haskell.org/pipermail/cabal-devel/2011-August/007714.html) for further
137details.