git.iko.soy/haskell.nix
on bfbbbd3 help sign in
haskell.nix/docs/user-guide.md
117 lines 4.2 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## Setup
11The general structure will be the same for haskell.nix, independent of
12the use of stack or cabal. Let us assume for now that we have
13generated a `pkgs.nix` expression in `nix`.
15- [Generating a `pkgs.nix` for a stack project](/user-guide-stack)
16- [Generating a `pkgs.nix` for a cabal project](/user-guide-cabal)
18## default.nix
20We will start with defining a helper function in our `default.nix`
21that will allow us to override the source imports with `-I
22haskell=/path/to/haskell.nix` in case we need it.
24```nix
25{ pkgs ? import <nixpkgs> {}
26}:
27let
28 overrideWith = override: default:
29 let
30 try = builtins.tryEval (builtins.findFile builtins.nixPath override);
31 in if try.success then
32 builtins.trace "using search host <${override}>" try.value
33 else
34 default;
35in
36```
38Next we will use this to import `haskell.nix`, `hackage.nix` and
39`stackage.nix` (if we use a stack project).
41**NOTE**: update the `rev` and `sha256` values to the recent ones as
42 found on GitHub. Especially `hackage.nix` and `stackage.nix` will
43 evolve with package release on hackage and stackage releases
44 respectively.
46```nix
47let
48 # all packages from hackage as nix expressions
49 hackage = import (overrideWith "hackage"
50 (pkgs.fetchFromGitHub { owner = "input-output-hk";
51 repo = "hackage.nix";
52 rev = "3180384b563ec7c7b46bca86b3ace0f32d04cde8";
53 sha256 = "19ndkn8pivli9plwq0wnx1cj126l89yk7jw9a0dj51ic3b2qhlb2";
54 name = "hackage-exprs-source"; }))
55 ;
56 # a different haskell infrastructure
57 haskell = import (overrideWith "haskell"
58 (pkgs.fetchFromGitHub { owner = "input-output-hk";
59 repo = "haskell.nix";
60 rev = "73f733ba8bbd11443dda713d1a2d4b7c50a5d408";
61 sha256 = "1p2srrxw2lac5krrg35waa251by98r2miwyg6zac9glpg2vmq3ip";
62 name = "haskell-lib-source"; }))
63 hackage;
65 # the set of all stackage snapshots
66 stackage = import (overrideWith "stackage"
67 (pkgs.fetchFromGitHub { owner = "input-output-hk";
68 repo = "stackage.nix";
69 rev = "2615a4e6b1651215ee400e62fcdcb195062a3d35";
70 sha256 = "08c8lb8x047hndwm1cb2zxixnjmrswfp5y18xp1v79cjqlva0qj6";
71 name = "stackage-snapshot-source"; }))
72 ;
73in
74```
76Finally we string this together and produce a package set:
78```nix
79let
80 # Import the file you will create in the stack-to-nix or cabal-to-nix step.
81 my-pkgs = import ./nix/pkgs.nix { inherit stackage; };
83 pkgSet = haskell.mkPkgSet {
84 inherit pkgs;
85 pkg-def = my-pkgs.pkg-def;
86 pkg-def-overlays = [
87 # this overlay will provide additional packages
88 # ontop of the package set. E.g. extra-deps
89 # for stack packages. or local packages for
90 # cabal.projects
91 my-pkgs.overlay
92 ];
93 modules = [
94 # specific package overrides would go here
95 # example:
96 # packages.cbors.patches = [ ./one.patch ];
97 # packages.cbors.flags.optimize-gmp = false;
98 ];
99 };
101in pkgSet.config.hsPkgs // { _config = pkgSet.config; }
102```
104With this setup you can then start building the components of
105interest:
107```bash
108nix build -f default.nix $pkg.components.library
109```
111to build the library for `$pkg` or
113```bash
114nix build -f default.nix $pkg.components.exes.$exe
115```
117to build a specific executable. The same holds for test suites and benchmarks.