git.iko.soy/typeable/cabal2nix
on v1.70 help sign in
typeable/cabal2nix/README.md
182 lines 7.4 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. However, if the source hash is not already in `cabal2nix`'s cache or
48provided using the `--sha256` option, `cabal2nix` still needs to download the source code to
49compute the hash, which obviously still causes network traffic.
50Run the utility with `--help` to see the complete list of supported command line flags.
52To add a new package to Nix, checkout the Nixpkgs project from
53https://github.com/nixos/nixpkgs.git and run
55 $ cd pkgs/development/libraries/haskell
56 $ mkdir foo
57 $ cabal2nix cabal://foo-1.0 >foo/default.nix
59Then add an appropriate attribute to
60`pkgs/top-level/haskell-packages.nix`, for example:
62 foo = callPackage ../development/libraries/haskell/foo {};
64`cabal2nix` can also build derivations for projects from other
65sources than hackage. You only need to provide an URI that points
66to a cabal project. The most common usecase for this is probably to
67generate a derivation for a project on the local file system:
69 aeson:$ cabal2nix ./.
70 # This file was auto-generated by cabal2nix. Please do NOT edit manually!
72 { cabal, attoparsec, blazeBuilder, deepseq, dlist, hashable, HUnit
73 , mtl, QuickCheck, scientific, syb, testFramework
74 , testFrameworkHunit, testFrameworkQuickcheck2, text, time
75 , unorderedContainers, vector
76 }
78 cabal.mkDerivation (self: {
79 pname = "aeson";
80 version = "0.7.0.2";
81 src = ./.;
82 buildDepends = [
83 attoparsec blazeBuilder deepseq dlist hashable mtl scientific syb
84 text time unorderedContainers vector
85 ];
86 testDepends = [
87 attoparsec HUnit QuickCheck testFramework testFrameworkHunit
88 testFrameworkQuickcheck2 text time unorderedContainers vector
89 ];
90 meta = {
91 homepage = "https://github.com/bos/aeson";
92 description = "Fast JSON parsing and encoding";
93 license = self.stdenv.lib.licenses.bsd3;
94 platforms = self.ghc.meta.platforms;
95 };
96 })
98This derivation will not fetch from hackage, but instead use the directory which
99contains the derivation as the source repository.
101`cabal2nix` currently supports the following respository types:
103* directory
104* source archive (zip, tar.gz, ...) from http or https URL or local file.
105* git, mercurial, svn or bazaar repository
107### Hackage4nix
109The `hackage4nix` utility re-generates *all* expressions found in the
110`nixpkgs` database in place. This is useful to ensure that all packages
111have been generated with a recent version of the tool-chain.
112Furthermore, `hackage4nix` adds default settings for the
113`meta.maintainers` and `meta.platforms` attribute if these aren't
114configured yet. Generally speaking, running
116 $ hackage4nix pkgs
118in your checked-out copy of the Nixpkgs tree should be a *no-op* ---
119i.e. no files should change! If there are changes, these indicate that a
120file has been modified manually, and then these changes must be
121investigated to find out what is going on.
123Last but not least, `hackage4nix` generates a list of all updates
124available from Hackage. (Run `cabal update` to make sure that your local
125copy of the Hackage database is up-to-date!) For example:
127 $ hackage4nix pkgs
128 The following updates are available:
130 WebBits-Html-1.0.1:
131 cabal2nix cabal://WebBits-Html-1.0.2 >pkgs/pkgs/development/libraries/haskell/WebBits-Html/default.nix
133 happstack-server-6.1.6:
134 cabal2nix cabal://happstack-server-6.2.1 >pkgs/pkgs/development/libraries/haskell/happstack/happstack-server.nix
135 cabal2nix cabal://happstack-server-6.2.2 >pkgs/pkgs/development/libraries/haskell/happstack/happstack-server.nix
137 primitive-0.3.1:
138 cabal2nix cabal://primitive-0.4 >pkgs/pkgs/development/libraries/haskell/primitive/default.nix
140 repa-2.1.1.5:
141 cabal2nix cabal://repa-2.1.1.6 >pkgs/pkgs/development/libraries/haskell/repa/default.nix
143 unix-compat-0.2.2.1:
144 cabal2nix cabal://unix-compat-0.3 >pkgs/pkgs/development/libraries/haskell/unix-compat/default.nix
146 vector-0.7.1:
147 cabal2nix cabal://vector-0.8 >pkgs/pkgs/development/libraries/haskell/vector/default.nix
149These updates can be performed automatically by running the `cabal2nix`
150command given by `hackage4nix`. If there is more than one possible
151update, then all of them will be shown. Note, however, that some updates
152break compilation of other packages, because they depend on very
153specific versions of their build inputs, so please be careful when
154performing updates!
156## Current State of Affairs
158The tool-chain is stable. As of today, 2013-04-12, virtually all Haskell
159packages available in Nix have been generated automatically from their
160Cabal files. There are only a handful of exceptions, which we cannot
161generate because these packages aren't available on Hackage. The list of
162those packages is hard-coded into the
163[`hackage4nix.hs`](https://github.com/NixOS/cabal2nix/blob/master/src/hackage4nix.hs)
164binary in the function `badPackagePaths`.
166Furthermore, Hackage4Nix will not re-generate packages that have been
167patched, i.e. that define any of the following attributes:
169 (pre|post)Configure
170 (pre|post)Install
171 patchPhase
172 patches
174These packages are considered for updates, however.
176The complete list of Haskell packages available in Nix is generated by
177the tool [`package-list`](http://github.com/peti/package-list),
178and published at <http://cryp.to/haskell-in-nixpkgs.txt>. Hackage picks
179it up from there and generates links on each package's homepage to the
180corresponding page in Hydra automatically. See [ticket
181875](http://www.haskell.org/pipermail/cabal-devel/2011-August/007714.html) for further
182details.