git.iko.soy/haskell.nix
on 9c6eb16 help sign in
haskell.nix/docs/tutorials/getting-started.md
114 lines 3.9 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 installed](https://nixos.org/download.html), you can start setting up your project.
10## Setting up the Cachix binary cache
12You can **avoid compiling GHC and nix-tools** by configuring [Cachix](https://cachix.org)
13so you can benefit from the binary cache built by CI:
15```bash
16$ nix-env -iA cachix -f https://cachix.org/api/v1/install
17installing 'cachix-0.3.8'
18building '/nix/store/bh176xhpk4wrjm56iahm86wf85jaz23v-user-environment.drv'...
19created 42 symlinks in user environment
21$ cachix use iohk
22Configured https://iohk.cachix.org binary cache in ~/.config/nix/nix.conf
23```
25## Scaffolding
27The following work with `stack.yaml` and `cabal.project` based
28projects.
30Add `default.nix`:
32```nix
33{ # Fetch the latest haskell.nix and import its default.nix
34 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}
36# haskell.nix provides access to the nixpkgs pins which are used by our CI, hence
37# you will be more likely to get cache hits when using these.
38# But you can also just use your own, e.g. '<nixpkgs>'
39, nixpkgsSrc ? haskellNix.sources.nixpkgs-2003
41# haskell.nix provides some arguments to be passed to nixpkgs, including some patches
42# and also the haskell.nix functionality itself as an overlay.
43, nixpkgsArgs ? haskellNix.nixpkgsArgs
45# import nixpkgs with overlays
46, pkgs ? import nixpkgsSrc nixpkgsArgs
47}: pkgs.haskell-nix.project {
48 # 'cleanGit' cleans a source directory based on the files known by git
49 src = pkgs.haskell-nix.haskellLib.cleanGit {
50 name = "haskell-nix-project";
51 src = ./.;
52 };
54```
56!!! note "git dependencies"
57 If you have git dependencies in your project, you'll need
58 to [calculate sha256 hashes for them](./source-repository-hashes.md).
60### Working with a project
62Top-level attributes are Haskell packages (incl. dependencies) part of your project.
64To build the library component of a package in the project run:
66```shell
67nix-build -A your-package-name.components.library
68```
70There are also other components such as `exes`, `tests`, `benchmarks` and `all`.
71To build an executable:
73```shell
74nix-build -A your-package-name.components.exes.your-exe-name
75```
77To open a shell for use with `cabal` run:
79```shell
80nix-shell -A shellFor
81cabal new-repl your-package-name:library:your-package-name
82cabal new-build your-package-name
83```
85To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
87### Pinning the [Haskell.nix][] version
89For simplicity's sake we will use `fetchTarball` for the examples in
90this documentation. This will always get the latest version, and is
91similar to an auto-updating Nix channel.
93However, in your own project, you may wish to pin [Haskell.nix][] (as
94you would pin Nixpkgs). This will make your builds reproducible, more
95predictable, and faster (because the fixed version is cached).
97Straightforward way of doing this is to change branch name to a revision.
99```nix
100{ # Fetch the latest haskell.nix and import its default.nix
101 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}
103...
104```
106There are other possible schemes for pinning. See
107[Bumping Hackage and Stackage snapshots](./hackage-stackage.md) and
108[Nix tutorial on reproducibility using pinning](https://nix.dev/tutorials/towards-reproducibility-pinning-nixpkgs.html).
110## Going forward
112There are a number of things to explore further in the tutorials section.
114[haskell.nix]: https://github.com/input-output-hk/haskell.nix