@@ -0,0 +1,112 @@
1+# Getting started with flakes
2+
3+This version of the getting started guide is for users who
4+are using [Nix Flakes](https://nixos.wiki/wiki/Flakes).
5+The non flakes version of the guide is [here](getting-started.md).
6+
7+`haskell.nix` can automatically translate your
8+[Cabal](https://cabal.readthedocs.io/en/latest/cabal-project.html)
9+or [Stack](https://docs.haskellstack.org/en/stable/README/#quick-start-guide)
10+project and its dependencies into Nix code.
11+
12+Assuming you have [Nix](https://nixos.org/download.html) installed, you can
13+start setting up your project.
14+
15+## Setting up the binary cache
16+
17+IMPORTANT: you *must* do this or you *will* build several copies of GHC!
18+
19+You can configure Nix to use our binary cache, which is pushed to by CI, so should contain the artifacts that you need.
20+
21+You 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).
22+
23+```
24+trusted-public-keys = [...] hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= [...]
25+substituters = [...] https://hydra.iohk.io [...]
26+```
27+
28+This 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).
29+
30+## Scaffolding
31+
32+The following work with `stack.yaml` and `cabal.project` based
33+projects.
34+
35+Add `flake.nix`:
36+
37+```nix
38+{
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+ };
54+ })
55+ ];
56+ pkgs = import nixpkgs { inherit system overlays; };
57+ flake = pkgs.helloProject.flake {};
58+ in flake // {
59+ # Built by `nix build .`
60+ defaultPackage = flake.packages."hello:exe:hello";
61+
62+ # This is used by `nix develop .` to open a shell for use with
63+ # `cabal`, `hlint` and `haskell-language-server`
64+ devShell = pkgs.helloProject.shellFor {
65+ tools = {
66+ cabal = "latest";
67+ hlint = "latest";
68+ haskell-language-server = "latest";
69+ };
70+ };
71+ });
72+}
73+```
74+
75+!!! note "git dependencies"
76+ If you have git dependencies in your project, you'll need
77+ to [calculate sha256 hashes for them](./source-repository-hashes.md).
78+
79+### Working with a project
80+
81+Top-level attributes are Haskell packages (incl. dependencies) part of your project.
82+
83+To build the library component of a package in the project run:
84+
85+```shell
86+nix build .#your-package-name:lib:your-package-name
87+```
88+
89+There are also other components such as `exe`, `test` and `benchmark`.
90+To build an executable:
91+
92+```shell
93+nix build .#your-package-name:exe:your-exe-name
94+```
95+
96+To use the `devShell` provided by the flake run:
97+
98+```shell
99+nix develop .
100+cabal repl your-package-name:lib:your-package-name
101+cabal build your-package-name
102+```
103+
104+To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).
105+
106+## Going forward
107+
108+Read through [project](../reference/library.md#project) function reference to see how the API works.
109+
110+There are a number of things to explore further in the tutorials section.
111+
112+[haskell.nix]: https://github.com/input-output-hk/haskell.nix