git.iko.soy/haskell.nix
on bcd346e help sign in
haskell.nix/docs/tutorials/getting-started-flakes.md
118 lines 4.1 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://hydra.iohk.io [...]
26```
28This can be tricky to get setup properly. If you're still having trouble getting cache hits, consult the corresponding [troubleshooting section](../reference/troubleshooting#why-am-i-building-ghc).
30## Scaffolding
32The following work with `stack.yaml` and `cabal.project` based
33projects.
35Add `flake.nix`:
37```nix
39 description = "A very basic flake";
40 inputs.haskellNix.url = "github:input-output-hk/haskell.nix";
41 inputs.nixpkgs.follows = "haskellNix/nixpkgs-unstable";
42 inputs.flake-utils.url = "github:numtide/flake-utils";
43 outputs = { self, nixpkgs, flake-utils, haskellNix }:
44 flake-utils.lib.eachSystem [ "x86_64-linux" "x86_64-darwin" ] (system:
45 let
46 overlays = [ haskellNix.overlay
47 (final: prev: {
48 # This overlay adds our project to pkgs
49 helloProject =
50 final.haskell-nix.project' {
51 src = ./.;
52 compiler-nix-name = "ghc8104";
53 # This is used by `nix develop .` to open a shell for use with
54 # `cabal`, `hlint` and `haskell-language-server`
55 shell.tools = {
56 cabal = {};
57 hlint = {};
58 haskell-language-server = {};
59 };
60 # Non-Haskell shell tools go here
61 shell.buildInputs = with pkgs; [
62 nixpkgs-fmt
63 ];
64 # This adds `js-unknown-ghcjs-cabal` to the shell.
65 shell.crossPlatform = p: [p.ghcjs];
66 };
67 })
68 ];
69 pkgs = import nixpkgs { inherit system overlays; inherit (haskellNix) config; };
70 flake = pkgs.helloProject.flake {
71 # This adds support for `nix build .#js-unknown-ghcjs-cabal:hello:exe:hello`
72 crossPlatforms = p: [p.ghcjs];
73 };
74 in flake // {
75 # Built by `nix build .`
76 defaultPackage = flake.packages."hello:exe:hello";
77 });
79```
81!!! note "git dependencies"
82 If you have git dependencies in your project, you'll need
83 to [calculate sha256 hashes for them](./source-repository-hashes.md).
85### Working with a project
87Top-level attributes are Haskell packages (incl. dependencies) part of your project.
89To build the library component of a package in the project run:
91```shell
92nix build .#your-package-name:lib:your-package-name
93```
95There are also other components such as `exe`, `test` and `benchmark`.
96To build an executable:
98```shell
99nix build .#your-package-name:exe:your-exe-name
100```
102To use the `devShell` provided by the flake run:
104```shell
105nix develop .
106cabal repl your-package-name:lib:your-package-name
107cabal build your-package-name
108```
110To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
112## Going forward
114Read through [project](../reference/library.md#project) function reference to see how the API works.
116There are a number of things to explore further in the tutorials section.
118[haskell.nix]: https://github.com/input-output-hk/haskell.nix