docs/tutorials/getting-started.md · haskell.nix · git.iko.soy

git.iko.soy/haskell.nix

on 80082ae help sign in

haskell.nix/docs/tutorials/getting-started.md

203 lines 6.6 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://cache.iog.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.settings.trusted-public-keys = [

29 "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ="

30];

31nix.settings.substituters = [

32 "https://cache.iog.io"

33];

34```

36NixOS-21.11 and older use slightly different settings.

38```

39# Binary Cache for Haskell.nix

40nix.binaryCachePublicKeys = [

41 "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ="

42];

43nix.binaryCaches = [

44 "https://cache.iog.io"

45];

46```

48This 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).

50## Niv

52[Niv](https://github.com/nmattia/niv) is a command line tool for keeping track of Nix project dependencies.

54This guide assumes that the `sources.haskellNix` will be set to point

55a pinned copy of the haskell.nix github repo. One easy way to do this

56is to use Niv. If you prefer not to use Niv another option is described

57in the in the "Using haskell.nix without niv" section of this document.

59If you want to use Nix Flakes to pin your dependencies then you should

60consider following the [Getting started with flakes](./getting-started-flakes.md)

61document instead of this one.

63After installing niv you can initialize niv and pin the latest haskell.nix

64commit by running the following in the root directory of the project:

66```

67niv init

68niv add input-output-hk/haskell.nix -n haskellNix

69```

71Then when you want to update to the latest version of haskellNix use:

73```

74niv update haskellNix

75```

77## Scaffolding

79The following work with `stack.yaml` and `cabal.project` based

80projects.

82Add `default.nix`:

84```nix

85let

86 # Read in the Niv sources

87 sources = import ./nix/sources.nix {};

88 # If ./nix/sources.nix file is not found run:

89 # niv init

90 # niv add input-output-hk/haskell.nix -n haskellNix

92 # Fetch the haskell.nix commit we have pinned with Niv

93 haskellNix = import sources.haskellNix {};

94 # If haskellNix is not found run:

95 # niv add input-output-hk/haskell.nix -n haskellNix

97 # Import nixpkgs and pass the haskell.nix provided nixpkgsArgs

98 pkgs = import

99 # haskell.nix provides access to the nixpkgs pins which are used by our CI,

100 # hence you will be more likely to get cache hits when using these.

101 # But you can also just use your own, e.g. '<nixpkgs>'.

102 haskellNix.sources.nixpkgs-unstable

103 # These arguments passed to nixpkgs, include some patches and also

104 # the haskell.nix functionality itself as an overlay.

105 haskellNix.nixpkgsArgs;

106in pkgs.haskell-nix.project {

107 # 'cleanGit' cleans a source directory based on the files known by git

108 src = pkgs.haskell-nix.haskellLib.cleanGit {

109 name = "haskell-nix-project";

110 src = ./.;

111 };

112 # Specify the GHC version to use.

113 compiler-nix-name = "ghc8102"; # Not required for `stack.yaml` based projects.

115```

117!!! note "git dependencies"

118 If you have git dependencies in your project, you'll need

119 to [calculate sha256 hashes for them](./source-repository-hashes.md).

121### Working with a project

123Top-level attributes are Haskell packages (incl. dependencies) part of your project.

125To build the library component of a package in the project run:

127```shell

128nix-build -A your-package-name.components.library

129```

131There are also other components such as `exes`, `tests`, `benchmarks` and `all`.

132To build an executable:

134```shell

135nix-build -A your-package-name.components.exes.your-exe-name

136```

138To cross compile use the `projectCross` attribute:

140```

141nix-build -A projectCross.ghcjs.hsPkgs.your-package-name.components.exes.your-exe-name

142nix-build -A projectCross.mingwW64.hsPkgs.your-package-name.components.exes.your-exe-name

143```

145To open a shell for use with `cabal`, `hlint` and `haskell-language-server` add `shell.nix`:

147```nix

148(import ./default.nix).shellFor {

149 tools = {

150 cabal = "3.2.0.0";

151 hlint = "latest";

152 haskell-language-server = "latest";

153 };

155```

157Then run:

159```shell

160nix-shell

161cabal new-repl your-package-name:library:your-package-name

162cabal new-build your-package-name

163```

165To open a shell for use with `stack` see [the following issue](https://github.com/input-output-hk/haskell.nix/issues/689#issuecomment-643832619).

167## Using haskell.nix without Niv

169If you would prefer not to use niv you can replace

170`sources = import ./nix/sources.nix {};` in the examples with:

172```nix

173let sources = {

174 haskellNix = builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/master.tar.gz";

175 };

176```

178The `fetchTarball` call above will always get the latest version, and is

179similar to an auto-updating Nix channel.

181However, in your own project, you may wish to pin [haskell.nix][] (as

182you would pin Nixpkgs). This will make your builds reproducible, more

183predictable, and faster (because the fixed version is cached).

185Straightforward way of doing this is to change the branch name to a revision.

187```nix

188let sources = {

189 haskellNix = builtins.fetchTarball "https://github.com/input-output-hk/haskell.nix/archive/f1a94a4c82a2ab999a67c3b84269da78d89f0075.tar.gz";

190 };

191```

193There are other possible schemes for pinning. See

194[Bumping Hackage and Stackage snapshots](./hackage-stackage.md) and

195[Nix tutorial on reproducibility using pinning](https://nix.dev/tutorials/towards-reproducibility-pinning-nixpkgs.html).

197## Going forward

199Read through [project](../reference/library.md#project) function reference to see how the API works.

201There are a number of things to explore further in the tutorials section.

203[haskell.nix]: https://github.com/input-output-hk/haskell.nix