git.iko.soy/haskell.nix
on 4e100b2 help sign in
haskell.nix/docs/tutorials/getting-started-flakes.md
142 lines 4.7 kB history raw
1# Getting started with flakes
3This version of the getting started guide is for users who
4are using [Nix Flakes](https://nixos.wiki/wiki/Flakes).
5The non flakes version of the guide is [here](getting-started.md).
7`haskell.nix` can automatically translate your
8[Cabal](https://cabal.readthedocs.io/en/latest/cabal-project.html)
9or [Stack](https://docs.haskellstack.org/en/stable/README/#quick-start-guide)
10project and its dependencies into Nix code.
12Assuming you have [Nix](https://nixos.org/download.html) installed, you can
13start setting up your project.
15## Setting up the binary cache
17IMPORTANT: you *must* do this or you *will* build several copies of GHC!
19You can configure Nix to use our binary cache, which is pushed to by CI, so should contain the artifacts that you need.
21You 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).
23```
24trusted-public-keys = [...] hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= [...]
25substituters = [...] https://cache.iog.io [...]
26```
28If you're running NixOS, you need to add/update the following in your `/etc/nixos/configuration.nix` files instead.
30```
31# Binary Cache for Haskell.nix
32nix.settings.trusted-public-keys = [
33 "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ="
34];
35nix.settings.substituters = [
36 "https://cache.iog.io"
37];
38```
40NixOS-21.11 and older use slightly different settings.
42```
43# Binary Cache for Haskell.nix
44nix.binaryCachePublicKeys = [
45 "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ="
46];
47nix.binaryCaches = [
48 "https://cache.iog.io"
49];
50```
52This can be tricky to get setup properly. If you're still having trouble getting cache hits, consult the corresponding [troubleshooting section](../troubleshooting.md#why-am-i-building-ghc).
54## Scaffolding
56The following work with `stack.yaml` and `cabal.project` based
57projects.
59Add `flake.nix`:
61```nix
63 description = "A very basic flake";
64 inputs.haskellNix.url = "github:input-output-hk/haskell.nix";
65 inputs.nixpkgs.follows = "haskellNix/nixpkgs-unstable";
66 inputs.flake-utils.url = "github:numtide/flake-utils";
67 outputs = { self, nixpkgs, flake-utils, haskellNix }:
68 flake-utils.lib.eachSystem [ "x86_64-linux" "x86_64-darwin" ] (system:
69 let
70 overlays = [ haskellNix.overlay
71 (final: prev: {
72 # This overlay adds our project to pkgs
73 helloProject =
74 final.haskell-nix.project' {
75 src = ./.;
76 compiler-nix-name = "ghc8104";
77 # This is used by `nix develop .` to open a shell for use with
78 # `cabal`, `hlint` and `haskell-language-server`
79 shell.tools = {
80 cabal = {};
81 hlint = {};
82 haskell-language-server = {};
83 };
84 # Non-Haskell shell tools go here
85 shell.buildInputs = with pkgs; [
86 nixpkgs-fmt
87 ];
88 # This adds `js-unknown-ghcjs-cabal` to the shell.
89 # shell.crossPlatforms = p: [p.ghcjs];
90 };
91 })
92 ];
93 pkgs = import nixpkgs { inherit system overlays; inherit (haskellNix) config; };
94 flake = pkgs.helloProject.flake {
95 # This adds support for `nix build .#js-unknown-ghcjs-cabal:hello:exe:hello`
96 # crossPlatforms = p: [p.ghcjs];
97 };
98 in flake // {
99 # Built by `nix build .`
100 defaultPackage = flake.packages."hello:exe:hello";
101 });
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 .#your-package-name:lib:your-package-name
117```
119There are also other components such as `exe`, `test` and `benchmark`.
120To build an executable:
122```shell
123nix build .#your-package-name:exe:your-exe-name
124```
126To use the `devShell` provided by the flake run:
128```shell
129nix develop .
130cabal repl your-package-name:lib:your-package-name
131cabal build your-package-name
132```
134To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
136## Going forward
138Read through [project](../reference/library.md#project) function reference to see how the API works.
140There are a number of things to explore further in the tutorials section.
142[haskell.nix]: https://github.com/input-output-hk/haskell.nix