git.iko.soy/haskell.nix
on 6c084e9 help sign in
haskell.nix/docs/tutorials/getting-started.md
138 lines 4.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](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## Scaffolding
40The following work with `stack.yaml` and `cabal.project` based
41projects.
43Add `default.nix`:
45```nix
46{ # Fetch the latest haskell.nix and import its default.nix
47 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz") {}
49# haskell.nix provides access to the nixpkgs pins which are used by our CI,
50# hence you will be more likely to get cache hits when using these.
51# But you can also just use your own, e.g. '<nixpkgs>'.
52, nixpkgsSrc ? haskellNix.sources.nixpkgs-2009
54# haskell.nix provides some arguments to be passed to nixpkgs, including some
55# patches and also the haskell.nix functionality itself as an overlay.
56, nixpkgsArgs ? haskellNix.nixpkgsArgs
58# import nixpkgs with overlays
59, pkgs ? import nixpkgsSrc nixpkgsArgs
60}: pkgs.haskell-nix.project {
61 # 'cleanGit' cleans a source directory based on the files known by git
62 src = pkgs.haskell-nix.haskellLib.cleanGit {
63 name = "haskell-nix-project";
64 src = ./.;
65 };
66 # Specify the GHC version to use.
67 compiler-nix-name = "ghc8102"; # Not required for `stack.yaml` based projects.
69```
71!!! note "git dependencies"
72 If you have git dependencies in your project, you'll need
73 to [calculate sha256 hashes for them](./source-repository-hashes.md).
75### Working with a project
77Top-level attributes are Haskell packages (incl. dependencies) part of your project.
79To build the library component of a package in the project run:
81```shell
82nix-build -A your-package-name.components.library
83```
85There are also other components such as `exes`, `tests`, `benchmarks` and `all`.
86To build an executable:
88```shell
89nix-build -A your-package-name.components.exes.your-exe-name
90```
92To cross compile use the `projectCross` attribute:
94```
95nix-build -A projectCross.ghcjs.hsPkgs.your-package-name.components.exes.your-exe-name
96nix-build -A projectCross.mingwW64.hsPkgs.your-package-name.components.exes.your-exe-name
97```
99To open a shell for use with `cabal` run:
101```shell
102nix-shell -A shellFor
103cabal new-repl your-package-name:library:your-package-name
104cabal new-build your-package-name
105```
107To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
109### Pinning the [haskell.nix][] version
111For simplicity's sake we will use `fetchTarball` for the examples in
112this documentation. This will always get the latest version, and is
113similar to an auto-updating Nix channel.
115However, in your own project, you may wish to pin [haskell.nix][] (as
116you would pin Nixpkgs). This will make your builds reproducible, more
117predictable, and faster (because the fixed version is cached).
119Straightforward way of doing this is to change the branch name to a revision.
121```nix
122{ # Fetch a specific haskell.nix and import its default.nix
123 haskellNix ? import (builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz") {}
125...
126```
128There are other possible schemes for pinning. See
129[Bumping Hackage and Stackage snapshots](./hackage-stackage.md) and
130[Nix tutorial on reproducibility using pinning](https://nix.dev/tutorials/towards-reproducibility-pinning-nixpkgs.html).
132## Going forward
134Read through [project](../reference/library.md#project) function reference to see how the API works.
136There are a number of things to explore further in the tutorials section.
138[haskell.nix]: https://github.com/input-output-hk/haskell.nix