git.iko.soy/haskell.nix
on 19052d8 help sign in
haskell.nix/docs/tutorials/getting-started-hix.md
203 lines 5.7 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://hydra.iohk.io [...]
33```
35This 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).
37## Installing Hix
39```
40nix-env -iA hix -f https://github.com/input-output-hk/haskell.nix/tarball/master
41```
43## Updating Hix (also updates hackage)
45```
46hix update
47```
49This is also necessary to make the latest nightly snapshot of hackage
50avaiable to nix.
52## Building with Hix
54To run `cabal build` in a nix-shell with all the dependencies required:
56```
57cabal unpack hello
58cd hello-1.0.0.2
59hix-shell --run 'cabal build'
60```
62Build with nix:
64```
65hix-build -A hsPkgs.hello.components.exes.hello
66```
68Cross compile to JavaScript:
70```
71hix-build -A projectCross.ghcjs.hsPkgs.hello.components.exes.hello
72```
74## Configuring Hix
76The configuration arguments for `Hix` can be (from highest precedence to lowest):
78* Passed on the command line with `--arg` (or `--argstr` for string args).
80* Placed in `nix/hix.nix` file in the project dir.
82* Placed in `~/.config/hix/hix.conf`
84For example to build with GHC 8.10.7:
86```
87hix-shell --argstr compiler-nix-name ghc8107 --run 'cabal build'
88```
90or add a `nix/hix.nix` or `~/.config/hix/hix.conf` file:
92```nix
93{ compiler-nix-name = "ghc8107"; }
94```
96Here are just a few of the other configuration arguments you could use
97in the files or on the command line (they are all optional):
99```nix
100{ name = "hello"; # for better error messages and derivation names
101 nixpkgsPin = "nixpkgs-unstable"; # or nixpkgs-2009 or nixpkgs-2003
102 nixpkgs = <nixpkgs>; # use this instead of nixpkgsPin
103 subDir = "some/sub/dir"; # sub dir containing the haskell project
104 projectFileName = "stack.yaml"; # use this project file
105 tools.haskell-language-server = "latest";
106 tools.hlint = "latest"; # Include the latest hls and hlint in the shell
107 index-state = "2021-02-22T00:00:00Z"; # It is normally best to put this in `cabal.project` (not here)
109# PLUS MANY MORE! Almost any argument you can pass to the project functions
110# or to `shellFor` can be used in as a Hix configuration argument.
113```
115## Adding Nix Support with Niv
117If you have a `nix/hix.nix` file with suitable configuration that
118you want to make available to users with Nix (without having to
119install Hix).
121[Niv](https://github.com/nmattia/niv) is a command line tool for keeping tack of Nix project dependencies.
123After installing niv you can initialize niv and pin the latest haskell.nix
124commit by running the following in the root directory of the project:
126```
127niv init
128niv add input-output-hk/haskell.nix -n haskellNix
129```
131Add `default.nix`:
133```nix
134(import (import nix/sources.nix).haskellNix {}).hix.project { src = ./.; }
135```
137If you want to also pin `nixpkgs` with Niv use:
139```nix
140let
141 sources = import nix/sources.nix;
142in
143 (import sources.haskellNix {}).hix.project {
144 inherit (sources) nixpkgs;
145 src = ./.;
146 }
147```
149Add `shell.nix`:
151```nix
152(import ./.).shell
153```
155When you want to update to the latest version of haskell.nix use:
157```
158niv update haskellNix
159```
161## Adding Nix Flake Support
163To add flake support that uses the `nix/hix.nix` configuration in your
164follow the [Getting started with flakes](getting-started.md) guide, but
165use `haskell-nix.hix.project` instead of `haskell-nix.project'`
167The `nixpkgs` used will need to be selected as a flake input (any selection
168made in `nix/hix.nix` will be ignored).
170Example `flake.nix` file:
172```nix
174 description = "A very basic flake";
175 inputs.haskellNix.url = "github:input-output-hk/haskell.nix";
176 inputs.nixpkgs.follows = "haskellNix/nixpkgs-unstable";
177 inputs.flake-utils.url = "github:numtide/flake-utils";
178 outputs = { self, nixpkgs, flake-utils, haskellNix }:
179 flake-utils.lib.eachSystem [ "x86_64-linux" "x86_64-darwin" ] (system:
180 let
181 overlays = [ haskellNix.overlay
182 (final: prev: {
183 # This overlay adds our project to pkgs
184 helloProject =
185 final.haskell-nix.hix.project {
186 src = ./.;
187 # Other project options can be put in `nix/hix.nix`
188 };
189 })
190 ];
191 pkgs = import nixpkgs { inherit system overlays; inherit (haskellNix) config; };
192 flake = pkgs.helloProject.flake {
193 # This adds support for `nix build .#js-unknown-ghcjs:hello:exe:hello`
194 crossPlatforms = p: [p.ghcjs];
195 };
196 in flake // {
197 # Built by `nix build .`
198 defaultPackage = flake.packages."hello:exe:hello";
199 });
201```