git.iko.soy/haskell.nix
on 12bac17 help sign in
haskell.nix/docs/tutorials/getting-started.md
127 lines 4.5 kB history raw
1# Getting started
3`haskell.nix` can automatically translate your
4[Cabal](https://cabal.readthedocs.io/en/latest/cabal-project.html)
5or [Stack](https://docs.haskellstack.org/en/stable/README/#quick-start-guide)
6project and its dependencies into Nix code.
8Assuming you have [Nix](https://nixos.org/download.html) installed, you can
9start setting up your project.
11## Setting up the Cachix binary cache
13You can **avoid compiling GHC and nix-tools** by configuring
14[Cachix](https://cachix.org) so you can benefit from the binary cache built by
15CI:
17```bash
18$ nix-env -iA cachix -f https://cachix.org/api/v1/install
19installing 'cachix-0.3.8'
20building '/nix/store/bh176xhpk4wrjm56iahm86wf85jaz23v-user-environment.drv'...
21created 42 symlinks in user environment
23$ cachix use iohk
24Configured https://iohk.cachix.org binary cache in ~/.config/nix/nix.conf
25```
27Note: `haskell.nix` currently uses multiple CI providers to build derivations and store outputs. To improve your chances of getting a cache hit, you might want to add the following additional substituter to `~/.config/nix/nix.conf`:
29```
30trusted-public-keys = [...] hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= [...]
31substituters = [...] https://hydra.iohk.io [...]
32```
34## Scaffolding
36The following work with `stack.yaml` and `cabal.project` based
37projects.
39Add `default.nix`:
41```nix
42{ # Fetch the latest haskell.nix and import its default.nix
43 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}
45# haskell.nix provides access to the nixpkgs pins which are used by our CI,
46# hence you will be more likely to get cache hits when using these.
47# But you can also just use your own, e.g. '<nixpkgs>'.
48, nixpkgsSrc ? haskellNix.sources.nixpkgs-2003
50# haskell.nix provides some arguments to be passed to nixpkgs, including some
51# patches and also the haskell.nix functionality itself as an overlay.
52, nixpkgsArgs ? haskellNix.nixpkgsArgs
54# import nixpkgs with overlays
55, pkgs ? import nixpkgsSrc nixpkgsArgs
56}: pkgs.haskell-nix.project {
57 # 'cleanGit' cleans a source directory based on the files known by git
58 src = pkgs.haskell-nix.haskellLib.cleanGit {
59 name = "haskell-nix-project";
60 src = ./.;
61 };
62 # For `cabal.project` based projects specify the GHC version to use.
63 compiler-nix-name = "ghc884"; # Not used for `stack.yaml` based projects.
65```
67!!! note "git dependencies"
68 If you have git dependencies in your project, you'll need
69 to [calculate sha256 hashes for them](./source-repository-hashes.md).
71### Working with a project
73Top-level attributes are Haskell packages (incl. dependencies) part of your project.
75To build the library component of a package in the project run:
77```shell
78nix-build -A your-package-name.components.library
79```
81There are also other components such as `exes`, `tests`, `benchmarks` and `all`.
82To build an executable:
84```shell
85nix-build -A your-package-name.components.exes.your-exe-name
86```
88To open a shell for use with `cabal` run:
90```shell
91nix-shell -A shellFor
92cabal new-repl your-package-name:library:your-package-name
93cabal new-build your-package-name
94```
96To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
98### Pinning the [haskell.nix][] version
100For simplicity's sake we will use `fetchTarball` for the examples in
101this documentation. This will always get the latest version, and is
102similar to an auto-updating Nix channel.
104However, in your own project, you may wish to pin [haskell.nix][] (as
105you would pin Nixpkgs). This will make your builds reproducible, more
106predictable, and faster (because the fixed version is cached).
108Straightforward way of doing this is to change the branch name to a revision.
110```nix
111{ # Fetch a specific haskell.nix and import its default.nix
112 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}
114...
115```
117There are other possible schemes for pinning. See
118[Bumping Hackage and Stackage snapshots](./hackage-stackage.md) and
119[Nix tutorial on reproducibility using pinning](https://nix.dev/tutorials/towards-reproducibility-pinning-nixpkgs.html).
121## Going forward
123Read through [project](../reference/library.md#project) function reference to see how the API works.
125There are a number of things to explore further in the tutorials section.
127[haskell.nix]: https://github.com/input-output-hk/haskell.nix