@@ -0,0 +1,203 @@
1+# Getting started with Hix
2+
3+The `hix` tools are wrappers for the various `nix` tools that
4+use `haskell.nix` without the need to add any `.nix` files.
5+
6+This is useful for:
7+
8+* A quick way to try out haskell.nix for new users.
9+
10+* Using haskell.nix to work on projects that do not have
11+ `.nix` files.
12+
13+* Testing to see if `haskell.nix` can build a project.
14+
15+* Making `flake` and `non flake` configurations to check `haskell.nix`
16+ treats them the same.
17+
18+## Installing Nix
19+
20+To use Hix you will need to install [Nix](https://nixos.org/download.html).
21+
22+## Setting up the binary cache
23+
24+IMPORTANT: you *must* do this or you *will* build several copies of GHC!
25+
26+You can configure Nix to use our binary cache, which is pushed to by CI, so should contain the artifacts that you need.
27+
28+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).
29+
30+```
31+trusted-public-keys = [...] hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= [...]
32+substituters = [...] https://hydra.iohk.io [...]
33+```
34+
35+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).
36+
37+## Installing Hix
38+
39+```
40+nix-env -iA hix -f https://github.com/input-output-hk/haskell.nix/tarball/master
41+```
42+
43+## Updating Hix (also updates hackage)
44+
45+```
46+hix update
47+```
48+
49+This is also necessary to make the latest nightly snapshot of hackage
50+avaiable to nix.
51+
52+## Building with Hix
53+
54+To run `cabal build` in a nix-shell with all the dependencies required:
55+
56+```
57+cabal unpack hello
58+cd hello-1.0.0.2
59+hix-shell --run 'cabal build'
60+```
61+
62+Build with nix:
63+
64+```
65+hix-build -A hsPkgs.hello.components.exes.hello
66+```
67+
68+Cross compile to JavaScript:
69+
70+```
71+hix-build -A projectCross.ghcjs.hsPkgs.hello.components.exes.hello
72+```
73+
74+## Configuring Hix
75+
76+The configuration arguments for `Hix` can be (from highest precedence to lowest):
77+
78+* Passed on the command line with `--arg` (or `--argstr` for string args).
79+
80+* Placed in `nix/hix.nix` file in the project dir.
81+
82+* Placed in `~/.config/hix/hix.conf`
83+
84+For example to build with GHC 8.10.5:
85+
86+```
87+hix-shell --argstr compiler-nix-name ghc8105 --run 'cabal build'
88+```
89+
90+or add a `nix/hix.nix` or `~/.config/hix/hix.conf` file:
91+
92+```nix
93+{ compiler-nix-name = "ghc8105"; }
94+```
95+
96+Here are just a few of the other configuration arguments you could use
97+in the files or on the command line (they are all optional):
98+
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)
108+
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.
111+
112+}
113+```
114+
115+## Adding Nix Support with Niv
116+
117+If you have a `nix/hix.nix` file with suitable configuration that
118+you want to make available to users with Nix (without having to
119+install Hix).
120+
121+[Niv](https://github.com/nmattia/niv) is a command line tool for keeping tack of Nix project dependencies.
122+
123+After installing niv you can initialize niv and pin the latest haskell.nix
124+commit by running the following in the root directory of the project:
125+
126+```
127+niv init
128+niv add input-output-hk/haskell.nix -n haskellNix
129+```
130+
131+Add `default.nix`:
132+
133+```nix
134+(import (import nix/sources.nix).haskellNix {}).hix.project { src = ./.; }
135+```
136+
137+If you want to also pin `nixpkgs` with Niv use:
138+
139+```nix
140+let
141+ sources = import nix/sources.nix;
142+in
143+ (import sources.haskellNix {}).hix.project {
144+ inherit (sources) nixpkgs;
145+ src = ./.;
146+ }
147+```
148+
149+Add `shell.nix`:
150+
151+```nix
152+(import ./.).shell
153+```
154+
155+When you want to update to the latest version of haskell.nix use:
156+
157+```
158+niv update haskellNix
159+```
160+
161+## Adding Nix Flake Support
162+
163+To add flake support that uses the `nix/hix.nix` configuration in your
164+follow the [Getting started with flakes](getting-started.md) guide, but
165+use `haskell-nix.hix.project` instead of `haskell-nix.project'`
166+
167+The `nixpkgs` used will need to be selected as a flake input (any selection
168+made in `nix/hix.nix` will be ignored).
169+
170+Example `flake.nix` file:
171+
172+```nix
173+{
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; };
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+ });
200+}
201+```
202+
203+