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

git.iko.soy/haskell.nix

on 4e100b2 help sign in

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

227 lines 6.3 kB history raw

1# Getting started with Hix

3The `hix` tools are wrappers for the various `nix` tools that

4use `haskell.nix` without the need to add any `.nix` files.

6This is useful for:

8* A quick way to try out haskell.nix for new users.

10* Using haskell.nix to work on projects that do not have

11 `.nix` files.

13* Testing to see if `haskell.nix` can build a project.

15* Making `flake` and `non flake` configurations to check `haskell.nix`

16 treats them the same.

18## Installing Nix

20To use Hix you will need to install [Nix](https://nixos.org/download.html).

22## Setting up the binary cache

24IMPORTANT: you *must* do this or you *will* build several copies of GHC!

26You can configure Nix to use our binary cache, which is pushed to by CI, so should contain the artifacts that you need.

28You 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).

30```

31trusted-public-keys = [...] hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= [...]

32substituters = [...] https://cache.iog.io [...]

33```

35If you're running NixOS, you need to add/update the following in your `/etc/nixos/configuration.nix` files instead.

37```

38# Binary Cache for Haskell.nix

39nix.settings.trusted-public-keys = [

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

41];

42nix.settings.substituters = [

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

44];

45```

47NixOS-21.11 and older use slightly different settings.

49```

50# Binary Cache for Haskell.nix

51nix.binaryCachePublicKeys = [

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

53];

54nix.binaryCaches = [

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

56];

57```

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

61## Installing Hix

63```

64nix-env -iA hix -f https://github.com/input-output-hk/haskell.nix/tarball/master

65```

67## Updating Hix (also updates hackage)

69```

70hix update

71```

73This is also necessary to make the latest nightly snapshot of hackage

74avaiable to nix.

76## Building with Hix

78To run `cabal build` in a nix-shell with all the dependencies required:

80```

81cabal unpack hello

82cd hello-1.0.0.2

83hix-shell --run 'cabal build'

84```

86Build with nix:

88```

89hix-build -A hsPkgs.hello.components.exes.hello

90```

92Cross compile to JavaScript:

94```

95hix-build -A projectCross.ghcjs.hsPkgs.hello.components.exes.hello

96```

98## Configuring Hix

100The configuration arguments for `Hix` can be (from highest precedence to lowest):

102* Passed on the command line with `--arg` (or `--argstr` for string args).

104* Placed in `nix/hix.nix` file in the project dir.

106* Placed in `~/.config/hix/hix.conf`

108For example to build with GHC 8.10.7:

110```

111hix-shell --argstr compiler-nix-name ghc8107 --run 'cabal build'

112```

114or add a `nix/hix.nix` or `~/.config/hix/hix.conf` file:

116```nix

117{ compiler-nix-name = "ghc8107"; }

118```

120Here are just a few of the other configuration arguments you could use

121in the files or on the command line (they are all optional):

123```nix

124{ name = "hello"; # for better error messages and derivation names

125 nixpkgsPin = "nixpkgs-unstable"; # or nixpkgs-2111 or nixpkgs-2105

126 nixpkgs = <nixpkgs>; # use this instead of nixpkgsPin

127 subDir = "some/sub/dir"; # sub dir containing the haskell project

128 projectFileName = "stack.yaml"; # use this project file

129 tools.haskell-language-server = "latest";

130 tools.hlint = "latest"; # Include the latest hls and hlint in the shell

131 index-state = "2021-02-22T00:00:00Z"; # It is normally best to put this in `cabal.project` (not here)

133# PLUS MANY MORE! Almost any argument you can pass to the project functions

134# or to `shellFor` can be used in as a Hix configuration argument.

137```

139## Adding Nix Support with Niv

141If you have a `nix/hix.nix` file with suitable configuration that

142you want to make available to users with Nix (without having to

143install Hix).

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

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

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

150```

151niv init

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

153```

155Add `default.nix`:

157```nix

158(import (import nix/sources.nix).haskellNix {}).hix.project { src = ./.; }

159```

161If you want to also pin `nixpkgs` with Niv use:

163```nix

164let

165 sources = import nix/sources.nix;

167 (import sources.haskellNix {}).hix.project {

168 inherit (sources) nixpkgs;

169 src = ./.;

170 }

171```

173Add `shell.nix`:

175```nix

176(import ./.).shell

177```

179When you want to update to the latest version of haskell.nix use:

181```

182niv update haskellNix

183```

185## Adding Nix Flake Support

187To add flake support that uses the `nix/hix.nix` configuration in your

188follow the [Getting started with flakes](getting-started.md) guide, but

189use `haskell-nix.hix.project` instead of `haskell-nix.project'`

191The `nixpkgs` used will need to be selected as a flake input (any selection

192made in `nix/hix.nix` will be ignored).

194Example `flake.nix` file:

196```nix

198 description = "A very basic flake";

199 inputs.haskellNix.url = "github:input-output-hk/haskell.nix";

200 inputs.nixpkgs.follows = "haskellNix/nixpkgs-unstable";

201 inputs.flake-utils.url = "github:numtide/flake-utils";

202 outputs = { self, nixpkgs, flake-utils, haskellNix }:

203 flake-utils.lib.eachSystem [ "x86_64-linux" "x86_64-darwin" ] (system:

204 let

205 overlays = [ haskellNix.overlay

206 (final: prev: {

207 # This overlay adds our project to pkgs

208 helloProject =

209 final.haskell-nix.hix.project {

210 src = ./.;

211 # Other project options can be put in `nix/hix.nix`

212 };

213 })

214 ];

215 pkgs = import nixpkgs { inherit system overlays; inherit (haskellNix) config; };

216 flake = pkgs.helloProject.flake {

217 # This adds support for `nix build .#js-unknown-ghcjs:hello:exe:hello`

218 crossPlatforms = p: [p.ghcjs];

219 };

220 in flake // {

221 # Built by `nix build .`

222 defaultPackage = flake.packages."hello:exe:hello";

223 });

225```