git.iko.soy/haskell.nix
on wineTestWrapperWithPath help sign in
haskell.nix/docs/reference/library.md
400 lines 13 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| Argument | Type | Description |
212|------------------|------|---------------------|
213| `name` | String | Optional name for better error messages. |
214| `src` | Path | Location of the cabal project files. |
215| `index-state` | Timestamp | Optional hackage index-state, eg. "2019-10-10T00:00:00Z". |
216| `index-sha256` | Sha256 | Optional hash of the truncated hackage index-state. |
217| `plan-sha256` | Sha256 | Optional hash of the plan-to-nix output (makes the plan-to-nix step a fixed output derivation). |
218| `cabalProject` | Path | Optional cabal project file (defaults to "${src}/cabal.project"). |
219| `ghc` | | Optional ghc to use |
220| `nix-tools` | | Optional nix-tools to use |
221| `hpack` | | Optional hpack to use |
222| `cabal-install` | | Optional cabal-install to use |
223| `configureArgs` | String | Optional extra arguments to pass to `cabal new-configure` (--enable-tests is included by default, include `--disable-tests` to override that). |
225## importAndFilterProject
227Imports from a derivation created by `callStackToNix`
228or `callCabalProjectToNix`.
230The result is an attrset with the following values:
232| Attribute | Type | Description |
233|----------------|------|-----------------------------------------------------|
234| `pkgs` | attrset | that can be passed to `mkStackPkgSet` (as `stack-pkgs`) or `mkCabalProjectPkgSet` (as `plan-pkgs`). |
235| `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). |
237## hackage
238## stackage
240## fetchExternal
242## cleanSourceHaskell
244```
245cleanSourceHaskell = { src, name ? null }: ...
246```
248Filters a source tree removing common filenames that are not Haskell
249build sources.
251This can avoid unecessary rebuilds when these files change.
253It's recommended to provide `name` so that the source derivation
254remains constant regardless of how it was fetched.
256Example:
258```
259src = pkgs.haskell-nix.cleanSourceHaskell {
260 src = ./.;
261 name = "myproject-src";
262};
263```
265## haskellSourceFilter
267```
268haskellSourceFilter = name: type: ...
269```
271This is a source filter function which cleans common build products
272and files not needed to do a Haskell build from a source directory.
274It should be used with `pkgs.lib.cleanSourceWith`. Alternatively,
275use the convenience function [`cleanSourceHaskell`](#cleansourcehaskell).
278## haskellLib
280Assorted functions for operating on [Haskell.nix][] data. This is
281distinct from `pkgs.haskell.lib` in the current Nixpkgs Haskell
282Infrastructure.
284### collectComponents and collectComponents'
286Extracts a selection of components from a Haskell [package set](#package-set).
288This can be used to filter out all test suites or benchmarks of
289your project, so that they can be built in Hydra (see check if you
290want to run the tests as well as build them).
292`collectComponents'` is an alias of `collectComponents` without
293predicate for filtering.
295```
296collectComponents =
297 group: packageSel: haskellPackages: ...
298collectComponents' = group: collectComponents (_: true)
299```
302| Argument | Type | Description |
303|-------------------|--------|---------------------|
304| `group` | String | A [sub-component type](#subComponentTypes). |
305| `packageSel` | A function `Package -> Bool` | A predicate to filter packages with. |
306| `haskellPackages` | [Package set](#package-set) | All packages in the build. |
308**Return value**: a recursive attrset mapping package names → component names → components.
310**Example**:
312```nix
313tests = collectComponents "tests" (package: package.identifier.name == "mypackage") hsPkgs;
314```
316Will result in moving derivations from `hsPkgs.mypackage.components.tests.unit-tests`
317to `tests.mypackage.unit-tests`.
319#### check
321This function turns a derivation that builds a test into one to run it.
323| Argument | Type | Description |
324|-------------------|--------|---------------------|
325| `drv` | Derivation | One of `$pkg.components.tests.$test`. |
327For convenience `$pkg.components.tests` are mapped with this function
328to `$pkg.checks`.
330This function is intended for use with `tests` but it should also work
331for `exes` and `benchmarks` if you just want to run them to make sure
332they execute.
334#### subComponentTypes
336Sub-component types identify [components](#component) and are one of:
338 - `sublibs`
339 - `foreignlibs`
340 - `exes`
341 - `tests`
342 - `benchmarks`
344# Package-set functions
346These functions exist within the `hsPkgs` package set.
348## shellFor
350Create a `nix-shell` [development
351environment](../user-guide/development.md) for developing one or more
352packages with `ghci` or `cabal v2-build` (but not Stack).
354```
355shellFor =
356 { packages, withHoogle ? true, exactDeps ? false, ...}: ...
357```
360| Argument | Type | Description |
361|----------------|------|---------------------|
362| `packages` | Function | Package selection function. It takes a list of [Haskell packages](#haskell-package) and returns a subset of these packages. |
363| `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. |
364| `exactDeps` | Boolean | Prevents the Cabal solver from choosing any package dependency other than what are in the package set. |
365| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |
367**Return value**: a derivation
369!!! warning
371 `exactDeps = true` will set the `CABAL_CONFIG` environment variable
372 to disable remote package servers. This is a
373 [known limitation](../dev/removing-with-package-wrapper.md)
374 which we would like to solve. Use `exactDeps = false` if this is a
375 problem.
378## ghcWithPackages
380Creates a `nix-shell` [development
381environment](../user-guide/development.md) including the given
382packages selected from this package set.
384**Parameter**: a package selection function.
386**Return value**: a derivation
388**Example**:
390```
391haskell.haskellPackages.ghcWithPackages (ps: with ps; [ lens conduit ])
392```
394## ghcWithHoogle
396The same as `ghcWithPackages`, except, a `hoogle` command with a
397Hoogle documentation index of the packages will be included in the
398shell.
400[haskell.nix]: https://github.com/input-output-hk/haskell.nix