git.iko.soy/haskell.nix
on f696ceb help sign in
haskell.nix/docs/tutorials/getting-started.md
191 lines 6.4 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 binary cache
13IMPORTANT: you *must* do this or you *will* build several copies of GHC!
15You can configure Nix to use our binary cache, which is pushed to by CI, so should contain the artifacts that you need.
17You need to add the following sections to `/etc/nix/nix.conf` or, if you are a trusted user, `~/.config/nix/nix.conf` (if you don't know what a "trusted user" is, you probably want to do the former).
19```
20trusted-public-keys = [...] hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= [...]
21substituters = [...] https://hydra.iohk.io [...]
22```
24If you're running NixOS, you need to add/update the following in your `/etc/nixos/configuration.nix` files instead.
26```
27# Binary Cache for Haskell.nix
28nix.binaryCachePublicKeys = [
29 "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ="
30];
31nix.binaryCaches = [
32 "https://hydra.iohk.io"
33];
34```
36This can be tricky to get setup properly. If you're still having trouble getting cache hits, consult the corresponding [troubleshooting section](../../troubleshooting#why-am-i-building-ghc).
38## Niv
40[Niv](https://github.com/nmattia/niv) is a command line tool for keeping tack of Nix project dependencies.
42This guide assumes that the `sources.haskellNix` will be set to point
43a pinned copy of the haskell.nix github repo. One easy way to do this
44is to use Niv. If you prefer not to use Niv another option is described
45in the in the "Using haskell.nix without niv" section of this document.
47If you want to use Nix Flakes to pin your dependencies then you should
48consider following the [Getting started with flakes](./getting-started-flakes.md)
49document instead of this one.
51After installing niv you can initialize niv and pin the latest haskell.nix
52commit by running the following in the root directory of the project:
54```
55niv init
56niv add input-output-hk/haskell.nix -n haskellNix
57```
59Then when you want to update to the latest version of haskellNix use:
61```
62niv update haskellNix
63```
65## Scaffolding
67The following work with `stack.yaml` and `cabal.project` based
68projects.
70Add `default.nix`:
72```nix
73let
74 # Read in the Niv sources
75 sources = import ./nix/sources.nix {};
76 # If ./nix/sources.nix file is not found run:
77 # niv init
78 # niv add input-output-hk/haskell.nix -n haskellNix
80 # Fetch the haskell.nix commit we have pinned with Niv
81 haskellNix = import sources.haskellNix {};
82 # If haskellNix is not found run:
83 # niv add input-output-hk/haskell.nix -n haskellNix
85 # Import nixpkgs and pass the haskell.nix provided nixpkgsArgs
86 pkgs = import
87 # haskell.nix provides access to the nixpkgs pins which are used by our CI,
88 # hence you will be more likely to get cache hits when using these.
89 # But you can also just use your own, e.g. '<nixpkgs>'.
90 haskellNix.sources.nixpkgs-2009
91 # These arguments passed to nixpkgs, include some patches and also
92 # the haskell.nix functionality itself as an overlay.
93 haskellNix.nixpkgsArgs;
94in pkgs.haskell-nix.project {
95 # 'cleanGit' cleans a source directory based on the files known by git
96 src = pkgs.haskell-nix.haskellLib.cleanGit {
97 name = "haskell-nix-project";
98 src = ./.;
99 };
100 # Specify the GHC version to use.
101 compiler-nix-name = "ghc8102"; # Not required for `stack.yaml` based projects.
103```
105!!! note "git dependencies"
106 If you have git dependencies in your project, you'll need
107 to [calculate sha256 hashes for them](./source-repository-hashes.md).
109### Working with a project
111Top-level attributes are Haskell packages (incl. dependencies) part of your project.
113To build the library component of a package in the project run:
115```shell
116nix-build -A your-package-name.components.library
117```
119There are also other components such as `exes`, `tests`, `benchmarks` and `all`.
120To build an executable:
122```shell
123nix-build -A your-package-name.components.exes.your-exe-name
124```
126To cross compile use the `projectCross` attribute:
128```
129nix-build -A projectCross.ghcjs.hsPkgs.your-package-name.components.exes.your-exe-name
130nix-build -A projectCross.mingwW64.hsPkgs.your-package-name.components.exes.your-exe-name
131```
133To open a shell for use with `cabal`, `hlint` and `haskell-language-server` add `shell.nix`:
135```nix
136(import ./default.nix).shellFor {
137 tools = {
138 cabal = "3.2.0.0";
139 hlint = "latest";
140 haskell-language-server = "latest";
141 };
143```
145Then run:
147```shell
148nix-shell
149cabal new-repl your-package-name:library:your-package-name
150cabal new-build your-package-name
151```
153To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
155## Using haskell.nix without Niv
157If you would prefer not to use niv you can replace
158`sources = import ./nix/sources.nix {};` in the examples with:
160```nix
161let sources = {
162 haskellNix = builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz";
163 };
164```
166The `fetchTarball` call above will always get the latest version, and is
167similar to an auto-updating Nix channel.
169However, in your own project, you may wish to pin [haskell.nix][] (as
170you would pin Nixpkgs). This will make your builds reproducible, more
171predictable, and faster (because the fixed version is cached).
173Straightforward way of doing this is to change the branch name to a revision.
175```nix
176let sources = {
177 haskellNix = builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz";
178 };
179```
181There are other possible schemes for pinning. See
182[Bumping Hackage and Stackage snapshots](./hackage-stackage.md) and
183[Nix tutorial on reproducibility using pinning](https://nix.dev/tutorials/towards-reproducibility-pinning-nixpkgs.html).
185## Going forward
187Read through [project](../reference/library.md#project) function reference to see how the API works.
189There are a number of things to explore further in the tutorials section.
191[haskell.nix]: https://github.com/input-output-hk/haskell.nix