git.iko.soy/haskell.nix
on 4ecc0aa help sign in
haskell.nix/docs/user-guide.md
120 lines 3.3 kB history raw
1# User Guide
3So you want to use `haskell.nix` with your stack or cabal project. The
4general approach will be to pick the right tool from `nix-tools` and
5produce a `pkgs.nix` expressions. Getting a copy of the haskell.nix,
6hackage.nix (and potentially stackage.nix) source will then equip us
7to produce derivations that we can `nix build`.
9## Installing `nix-tools`
11To build the latest `nix-tools` and store the result at `./nt`, run:
13```bash
14nix build -f https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz nix-tools --out-link nt
15```
17If you would like to then install `nix-tools` into your profile, run:
19```bash
20nix-env -i ./nt
21```
23## Setup
25The general structure will be the same for haskell.nix, independent of
26the use of stack or cabal. Let us assume for now that we have
27generated a `pkgs.nix` expression in `nix`.
29- [Generating a `pkgs.nix` for a stack project](/user-guide-stack)
30- [Generating a `pkgs.nix` for a cabal project](/user-guide-cabal)
32## default.nix
34We will start with defining a helper function in our `default.nix`
35that will allow us to override the source imports with `-I
36haskell=/path/to/haskell.nix` in case we need it.
38```nix
39{ pkgs ? import <nixpkgs> {}
40}:
41let
42 overrideWith = override: default:
43 let
44 try = builtins.tryEval (builtins.findFile builtins.nixPath override);
45 in if try.success then
46 builtins.trace "using search host <${override}>" try.value
47 else
48 default;
49in
50```
52Next we will use this to import `haskell.nix`.
54**NOTE**: update the `rev` and `sha256` values to the recent ones as
55 found on GitHub. Especially `haskell.hackage` and `haskell.stackage`
56 will evolve with package release on hackage and stackage releases
57 respectively.
59```nix
60let
61 haskellLib = pkgs.fetchFromGitHub {
62 owner = "input-output-hk";
63 repo = "haskell.nix";
64 rev = "5180ae9d78756509c81b98b8e6d974e350b15752";
65 sha256 = "0fbnnvymdp2qb09wlqy6ga8wsyhglx607cjdfg510s1gs756v9yx";
66 name = "haskell-lib-source";
67 };
68 haskell = import (overrideWith "haskell" haskellLib) { inherit pkgs; };
69in
70```
72Finally we string this together and produce a package set:
74```nix
75let
76 # Import the file you will create in the stack-to-nix or cabal-to-nix step.
77 my-pkgs = import ./nix/pkgs.nix;
79 # Stack projects use the mkStackPkgSet helper function
80 pkgSet = haskell.mkStackPkgSet {
81 stack-pkgs = my-pkgs;
82 pkg-def-overlays = [];
83 modules = [];
84 };
86 # Cabal projects use mkPkgSet
87 pkgSet = haskell.mkPkgSet {
88 pkg-def = my-pkgs.pkg-def;
89 pkg-def-extras = [
90 # these extras will provide additional packages
91 # ontop of the package set. E.g. extra-deps
92 # for stack packages. or local packages for
93 # cabal.projects
94 my-pkgs.extras
95 ];
96 modules = [
97 # specific package overrides would go here
98 # example:
99 # packages.cbors.patches = [ ./one.patch ];
100 # packages.cbors.flags.optimize-gmp = false;
101 ];
102 };
104in pkgSet.config.hsPkgs // { _config = pkgSet.config; }
105```
107With this setup you can then start building the components of
108interest:
110```bash
111nix build -f default.nix $pkg.components.library
112```
114to build the library for `$pkg` or
116```bash
117nix build -f default.nix $pkg.components.exes.$exe
118```
120to build a specific executable. The same holds for test suites and benchmarks.