docs/reference/library.md · haskell.nix · git.iko.soy

git.iko.soy/haskell.nix

on 9d4cb21 help sign in

haskell.nix/docs/reference/library.md

332 lines 10 kB history raw

1[Haskell.nix][] contains a library of functions for creating buildable

2package sets from their Nix expression descriptions. The library is

3what you get when importing [Haskell.nix][]. It might be helpful to

4load the library in the [Nix REPL](../user-guide.md#using-nix-repl) to

5test things.

7 * [Types](#types) — the kinds of data that you will encounter working with [Haskell.nix][].

8 * [Top-level attributes](#top-level-attributes) — Functions and derivations defined in the Haskell.nix attrset.

9 * [Package-set functions](#package-set-functions) — Helper functions defined on the `hsPkgs` package set.

11# Types

13## Package Set

15The result of `mkPkgSet`. This is an application of the NixOS module

16system.

18```

20 options = { ... };

21 config = {

22 hsPkgs = { ... };

23 packages = { ... };

24 compiler = {

25 version = "X.Y.Z";

26 nix-name = "ghcXYZ";

27 packages = { ... };

28 };

29 };

31```

33| Attribute | Type | Description |

34|----------------|------|-----------------------------------------------------|

35| `options` | Module options | The combination of all options set through the `modules` argument passed to `mkPkgsSet`. |

36| `config` | | The result of evaluating and applying the `options` with [Haskell.nix][] |

37| `.hsPkgs` | Attrset of [Haskell Packages](#haskell-package) | Buildable packages, created from `packages` |

38| `.packages` | Attrset of [Haskell Package descriptions](#haskell-package-descriptions) | Configuration for each package in `hsPkgs` |

39| `.compiler` | Attrset | |

43## Haskell Package description

45The _Haskell package descriptions_ are values of the

46`pkgSet.config.packages` attrset. These are not derivations, but just

47the configuration for building an individual package. The

48configuration options are described under `packages.<name>` in [Module

49options](./modules.md).

51## Component description

53The _component descriptions_ are values of the

54`pkgSet.config.packages.<package>.components` attrset. These are not

55derivations, but just the configuration for building an individual

56component. The configuration options are described under

57`packages.<name>.components.*` in [Module options](./modules.md).

60## Haskell Package

62In [Haskell.nix][], a _Haskell package_ is a derivation which has a

63`components` attribute. This derivation is actually just for the

64package `Setup.hs` script, and isn't very interesting. To actually use

65the package, look within the components structure.

67```

68components = {

69 library = COMPONENT;

70 exes = { NAME = COMPONENT; };

71 tests = { NAME = COMPONENT; };

72 benchmarks = { NAME = COMPONENT; };

73 all = COMPONENT;

75```

77## Component

79In [Haskell.nix][], a _component_ is a derivation corresponding to a

80[Cabal component](https://www.haskell.org/cabal/users-guide/developing-packages.html)

81of a package.

83[Haskell.nix][] also defines a special `all` component, which is the

84union of all components in the package.

86## Identifier

88A package identifier is an attrset pair of `name` and `version`.

90## Extras

92Extras allow adding more packages to the package set. These will be

93functions taking a single parameter `hackage`. They should return an

94attrset of package descriptions.

96## Modules

98Modules are the primary method of configuring building of the package

99set. They are either:

1011. an attrset containing [option declarations](./options.md), or

1022. a function that returns an attrset containing option declarations.

104If using the function form of a module, the following named parameters

105will be passed to it:

107| Argument | Type | Description |

108|------------------|------|---------------------|

109| `haskellLib` | attrset | The [haskellLib](#haskelllib) utility functions. |

110| `pkgs` | | The Nixpkgs collection. |

111| `pkgconfPkgs` | | A mapping of cabal build-depends names to Nixpkgs packages. (TODO: more information about this) |

112| `buildModules` | | |

113| `config` | | |

114| `options` | | |

117# Top-level attributes

119## mkStackPkgSet

121Creates a [package set](#package-set) based on the `pkgs.nix` output

122of `stack-to-nix`.

124```nix

125mkStackPkgSet =

126 { stack-pkgs, pkg-def-extras ? [], modules ? []}: ...

127```

129| Argument | Type | Description |

130|------------------|------|---------------------|

131| `stack-pkgs` | | `import ./pkgs.nix` — The imported file generated by `stack‑to‑nix`. |

132| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |

133| `modules` | List of [Modules](#modules) | For overriding the package set. |

135**Return value**: a [`pkgSet`](#package-set)

137## mkCabalProjectPkgSet

139Creates a [package set](#package-set) based on the `pkgs.nix` output

140of `plan-to-nix`.

142```nix

143mkCabalProjectPkgSet =

144 { plan-pkgs, pkg-def-extras ? [], modules ? []}: ...

145```

147| Argument | Type | Description |

148|------------------|------|---------------------|

149| `plan-pkgs` | | `import ./pkgs.nix` — The imported file generated by `plan‑to‑nix`. |

150| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |

151| `modules` | List of [Modules](#modules) | For overriding the package set. |

153**Return value**: a [`pkgSet`](#package-set)

155## mkPkgSet

157This is the base function used by both `mkStackPkgSet` and

158`mkCabalProjectPkgSet`.

160**Return value**: a [`pkgSet`](#package-set)

162## snapshots

164This is an attrset of `hsPkgs` packages from Stackage.

166## haskellPackages

168A `hsPkgs` package set, which is one of the recent LTS Haskell

169releases from [`snapshots`](#snapshots).

171The chosen LTS is updated occasionally in [Haskell.nix][], though a

172manual process.

174## nix-tools

176A derivation containing the `nix-tools` [command-line tools](commands.md).

178## callStackToNix

180Runs `stack-to-nix` and produces the output needed for

181`importAndFilterProject`.

183**Example**:

185```nix

186 pkgSet = mkStackPkgSet {

187 stack-pkgs = (importAndFilterProject (callStackToNix {

188 src = ./.;

189 })).pkgs;

190 pkg-def-extras = [];

191 modules = [];

192 };

193```

196## callCabalProjectToNix

198Runs `cabal new-configure` and `plan-to-nix` and produces the output

199needed for `importAndFilterProject`.

201**Example**:

203```nix

204 pkgSet = mkCabalProjectPkgSet {

205 plan-pkgs = (importAndFilterProject (callCabalProjectToNix {

206 index-state = "2019-04-30T00:00:00Z";

207 src = ./.;

208 })).pkgs;

209```

211## importAndFilterProject

213Imports from a derivation created by `callStackToNix`

214or `callCabalProjectToNix`.

216The result is an attrset with the following values:

218| Attribute | Type | Description |

219|----------------|------|-----------------------------------------------------|

220| `pkgs` | attrset | that can be passed to `mkStackPkgSet` (as `stack-pkgs`) or `mkCabalProjectPkgSet` (as `plan-pkgs`). |

221| `nix` | | this can be built and cached so that the amount built in the evaluation phase is not too great (helps to avoid timeouts on Hydra). |

223## hackage

224## stackage

226## fetchExternal

228## cleanSourceHaskell

230## haskellLib

232Assorted functions for operating on [Haskell.nix][] data. This is

233distinct from `pkgs.haskell.lib` in the current Nixpkgs Haskell

234Infrastructure.

236### collectComponents

238Extracts a selection of components from a Haskell [package set](#package-set).

240This can be used to filter out all test suites or benchmarks of

241your project, so that they can be built in Hydra.

243```

244collectComponents =

245 group: packageSel: haskellPackages: ...

246```

249| Argument | Type | Description |

250|-------------------|--------|---------------------|

251| `group` | String | A [sub-component type](#subComponentTypes). |

252| `packageSel` | A function `Package -> Bool` | A predicate to filter packages with. |

253| `haskellPackages` | [Package set](#package-set) | All packages in the build. |

255**Return value**: a recursive attrset mapping package names → component names → components.

257**Example**:

259```nix

260tests = collectComponents "tests" (package: package.identifier.name == "mypackage") hsPkgs;

261```

263Will result in moving derivations from `hsPkgs.mypackage.components.tests.unit-tests`

264to `tests.mypackage.unit-tests`.

266#### subComponentTypes

268Sub-component types identify [components](#component) and are one of:

270 - `sublibs`

271 - `foreignlibs`

272 - `exes`

273 - `tests`

274 - `benchmarks`

276# Package-set functions

278These functions exist within the `hsPkgs` package set.

280## shellFor

282Create a `nix-shell` [development

283environment](../user-guide/development.md) for developing one or more

284packages with `ghci` or `cabal v2-build` (but not Stack).

286```

287shellFor =

288 { packages, withHoogle ? true, exactDeps ? false, ...}: ...

289```

292| Argument | Type | Description |

293|----------------|------|---------------------|

294| `packages` | Function | Package selection function. It takes a list of [Haskell packages](#haskell-package) and returns a subset of these packages. |

295| `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. |

296| `exactDeps` | Boolean | Prevents the Cabal solver from choosing any package dependency other than what are in the package set. |

297| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |

299**Return value**: a derivation

301!!! warning

303 `exactDeps = true` will set the `CABAL_CONFIG` environment variable

304 to disable remote package servers. This is a

305 [known limitation](../dev/removing-with-package-wrapper.md)

306 which we would like to solve. Use `exactDeps = false` if this is a

307 problem.

310## ghcWithPackages

312Creates a `nix-shell` [development

313environment](../user-guide/development.md) including the given

314packages selected from this package set.

316**Parameter**: a package selection function.

318**Return value**: a derivation

320**Example**:

322```

323haskell.haskellPackages.ghcWithPackages (ps: with ps; [ lens conduit ])

324```

326## ghcWithHoogle

328The same as `ghcWithPackages`, except, a `hoogle` command with a

329Hoogle documentation index of the packages will be included in the

330shell.

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