git.iko.soy/haskell.nix
on 926818e help sign in
haskell.nix/docs/reference/library.md
476 lines 19 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](../tutorials/development.md#using-nix-repl) to
5test things.
7 * [Data structures](#data-structures) — 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# Data structures
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; };
74```
76## Component
78In [Haskell.nix][], a _component_ is a derivation corresponding to a
79[Cabal component](https://www.haskell.org/cabal/users-guide/developing-packages.html)
80of a package.
82## Identifier
84A package identifier is an attrset pair of `name` and `version`.
86## Extras
88Extras allow adding more packages to the package set. These will be
89functions taking a single parameter `hackage`. They should return an
90attrset of package descriptions.
92## Modules
94Modules are the primary method of configuring building of the package
95set. They are either:
971. an attrset containing [option declarations](./modules.md), or
982. a function that returns an attrset containing option declarations.
100If using the function form of a module, the following named parameters
101will be passed to it:
103| Argument | Type | Description |
104|------------------|------|---------------------|
105| `haskellLib` | attrset | The [haskellLib](#haskelllib) utility functions. |
106| `pkgs` | | The Nixpkgs collection. |
107| `pkgconfPkgs` | | A mapping of cabal build-depends names to Nixpkgs packages. (TODO: more information about this) |
108| `buildModules` | | |
109| `config` | | |
110| `options` | | |
113# Top-level attributes
115## project'
117Function that accepts attribute set with a `src` attribute and looks for `stack.yaml` file relative to it.
119If file exists, it calls [stackProject](#stackproject') function. Otherwise it will call [cabalProject](#cabalproject') function.
121**Example**:
123```nix
124pkgs.haskell-nix.project' {
125 # 'cleanGit' cleans a source directory based on the files known by git
126 src = pkgs.haskell-nix.haskellLib.cleanGit {
127 name = "haskell-nix-project";
128 src = ./.;
129 };
131```
133## stackProject'
135A function calling [callStackToNix](#callstacktonix) with all arguments.
137Then feeding its result into [mkStackPkgSet](#mkstackpkgset) passing also
138`pkg-def-extras` and `modules` arguments.
140**Return value**:
142| Attribute | Type | Description |
143|-------------------|--------------------------------------------------|----------------------------------------------------------------------------|
144| `hsPkgs` | Attrset of [Haskell Packages](#haskell-package) | Buildable packages, created from `packages` |
145| `stack-nix` | | `projectNix` attribute of [`callStackToNix`](#callstacktonix) return value |
146| `shellFor` | Function | [`shellFor`](#shellfor) |
147| `ghcWithHoogle` | Function | [`ghcWithHoogle`](#ghcwithhoogle) |
148| `ghcWithPackages` | Function | [`ghcWithPackages`](#ghcwithpackages) |
151## cabalProject'
153A function calling [callCabalProjectToNix](#callcabalprojecttonix) with all arguments.
155Then feeding its result into [mkCabalProjectPkgSet](#mkcabalprojectpkgset) passing also
156`pkg-def-extras`, `extra-hackages` and `modules` arguments.
158**Return value**:
160| Attribute | Type | Description |
161|-------------------|--------------------------------------------------|-----------------------------------------------------------------------------|
162| `hsPkgs` | Attrset of [Haskell Packages](#haskell-package) | Buildable packages, created from `packages` |
163| `plan-nix` | | `projectNix` attribute of [`callCabalProjectToNix`](#callcabalprojecttonix) return value |
164| `index-state` | | `index-state` attribute of [`callCabalProjectToNix`](#callcabalprojecttonix) return value |
165| `shellFor` | Function | [`shellFor`](#shellfor) |
166| `ghcWithHoogle` | Function | [`ghcWithHoogle`](#ghcwithhoogle) |
167| `ghcWithPackages` | Function | [`ghcWithPackages`](#ghcwithpackages) |
168| `projectCross` | Attrset | Like `pkgs.pkgsCross.<system>` from nixpkgs `p.projectCross.<system>` returns the project results for cross compilation (where system is a member of nixpkgs lib.systems.examples). So `p.projectCross.ghcjs.hsPkgs` is the same as `hsPkgs` but compiled with ghcjs |
169| `appendModule` | Function | Re-eval the project with an extra module (or module list). |
170| `extend` and `appendOverlays` | Function | Modify a project, or add attributes, through overlays: `p.extend(final: prev: { })`. The overlays are carried-over `projectCross` and `appendModule` invocations. |
172## project, cabalProject and stackProject
174These versions of the function are the same as project', cabalProject'
175and stackProject', but `hsPkgs` attributes are also included in the
176return value directly. That way a package can be referenced as
177`(project {...}).foo` instead of `(project' {...}).hsPkgs.foo`.
179## mkStackPkgSet
181Creates a [package set](#package-set) based on the `pkgs.nix` output
182of `stack-to-nix`.
184```nix
185mkStackPkgSet =
186 { stack-pkgs, pkg-def-extras ? [], modules ? []}: ...
187```
189| Argument | Type | Description |
190|------------------|------|---------------------|
191| `stack-pkgs` | | `import ./pkgs.nix` — The imported file generated by `stack‑to‑nix`. |
192| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
193| `modules` | List of [Modules](#modules) | For overriding the package set. |
195**Return value**: a [`pkgSet`](#package-set)
197## mkCabalProjectPkgSet
199Creates a [package set](#package-set) based on the `pkgs.nix` output
200of `plan-to-nix`.
202```nix
203mkCabalProjectPkgSet =
204 { plan-pkgs, pkg-def-extras ? [], modules ? []}: ...
205```
207| Argument | Type | Description |
208|------------------|------|---------------------|
209| `plan-pkgs` | | `import ./pkgs.nix` — The imported file generated by `plan‑to‑nix`. |
210| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
211| `modules` | List of [Modules](#modules) | For overriding the package set. |
213**Return value**: a [`pkgSet`](#package-set)
215## mkPkgSet
217This is the base function used by both `mkStackPkgSet` and
218`mkCabalProjectPkgSet`.
220**Return value**: a [`pkgSet`](#package-set)
222## snapshots
224This is an attrset of `hsPkgs` packages from Stackage.
226## haskellPackages
228A `hsPkgs` package set, which is one of the recent LTS Haskell
229releases from [`snapshots`](#snapshots).
231The chosen LTS is updated occasionally in [Haskell.nix][], though a
232manual process.
234## nix-tools
236A derivation containing the `nix-tools` [command-line tools](commands.md).
238## callStackToNix
240Runs `stack-to-nix` and produces the output needed for
241`importAndFilterProject`.
243**Example**:
245```nix
246 pkgSet = mkStackPkgSet {
247 stack-pkgs = (importAndFilterProject (callStackToNix {
248 src = ./.;
249 })).pkgs;
250 pkg-def-extras = [];
251 modules = [];
252 };
253```
256## callCabalProjectToNix
258Runs `cabal new-configure` and `plan-to-nix` and produces the output
259needed for `importAndFilterProject`.
261**Example**:
263```nix
264 pkgSet = mkCabalProjectPkgSet {
265 plan-pkgs = (importAndFilterProject (callCabalProjectToNix {
266 index-state = "2019-04-30T00:00:00Z";
267 src = ./.;
268 })).pkgs;
269```
271| Argument | Type | Description |
272|----------------------|------|---------------------|
273| `name` | String | Optional name for better error messages. |
274| `src` | Path | Location of the cabal project files. |
275| `compiler-nix-name` | String | The name of the ghc compiler to use eg. "ghc884" |
276| `index-state` | Timestamp | Optional hackage index-state, eg. "2019-10-10T00:00:00Z". |
277| `index-sha256` | Sha256 | Optional hash of the truncated hackage index-state. |
278| `plan-sha256` | Sha256 | Optional hash of the plan-to-nix output (makes the plan-to-nix step a fixed output derivation). |
279| `cabalProject` | String | Optional cabal project file contents (defaults to readFile "${src}/cabal.project"). |
280| `cabalProjectLocal` | String | Optional cabal project file contents (defaults to readFile "${src}/cabal.project.local"). |
281| `cabalProjectFreeze` | String | Optional cabal project file contents (defaults to readFile "${src}/cabal.project.freeze"). |
282| `ghc` | | Deprecated. Use `compiler-nix-name` instead. Optional ghc to use |
283| `nix-tools` | | Optional nix-tools to use |
284| `hpack` | | Optional hpack to use |
285| `cabal-install` | | Optional cabal-install to use |
286| `configureArgs` | String | Optional extra arguments to pass to `cabal new-configure` (--enable-tests is included by default, include `--disable-tests` to override that). |
288## importAndFilterProject
290Imports from a derivation created by `callStackToNix`
291or `callCabalProjectToNix`.
293The result is an attrset with the following values:
295| Attribute | Type | Description |
296|----------------|------|-----------------------------------------------------|
297| `pkgs` | attrset | that can be passed to `mkStackPkgSet` (as `stack-pkgs`) or `mkCabalProjectPkgSet` (as `plan-pkgs`). |
298| `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). |
300## hackage
301## stackage
303## fetchExternal
305## cleanSourceHaskell
307```
308cleanSourceHaskell = { src, name ? null }: ...
309```
311Filters a source tree removing common filenames that are not Haskell
312build sources.
314This can avoid unecessary rebuilds when these files change.
316It's recommended to provide `name` so that the source derivation
317remains constant regardless of how it was fetched.
319Example:
321```
322src = pkgs.haskell-nix.cleanSourceHaskell {
323 src = ./.;
324 name = "myproject-src";
325};
326```
328## haskellSourceFilter
330```
331haskellSourceFilter = name: type: ...
332```
334This is a source filter function which cleans common build products
335and files not needed to do a Haskell build from a source directory.
337It should be used with `pkgs.lib.cleanSourceWith`. Alternatively,
338use the convenience function [`cleanSourceHaskell`](#cleansourcehaskell).
341## haskellLib
343Assorted functions for operating on [Haskell.nix][] data. This is
344distinct from `pkgs.haskell.lib` in the current Nixpkgs Haskell
345Infrastructure.
347### collectComponents, collectComponents'
349Extracts a selection of components from a Haskell [package set](#package-set).
351This can be used to filter out all test suites or benchmarks of
352your project, so that they can be built in Hydra (see check if you
353want to run the tests as well as build them).
355`collectComponents'` is an alias of `collectComponents` without
356predicate for filtering.
358```
359collectComponents =
360 group: packageSel: haskellPackages: ...
361collectComponents' = group: collectComponents (_: true)
362```
365| Argument | Type | Description |
366|-------------------|--------|---------------------|
367| `group` | String | A [sub-component type](#subComponentTypes). |
368| `packageSel` | A function `Package -> Bool` | A predicate to filter packages with. |
369| `haskellPackages` | [Package set](#package-set) | All packages in the build. |
371**Return value**: a recursive attrset mapping package names → component names → components.
373**Example**:
375```nix
376tests = collectComponents "tests" (package: package.identifier.name == "mypackage") hsPkgs;
377```
379Will result in moving derivations from `hsPkgs.mypackage.components.tests.unit-tests`
380to `tests.mypackage.unit-tests`.
382### collectChecks, collectChecks'
384These are just like `collectComponents` and `collectComponents'`, except that they collect
385the `checks` attributes of packages (which aren't components, and so can't be collected
386by the other functions.
388#### check
390This function turns a derivation that builds a test into one to run it.
392| Argument | Type | Description |
393|-------------------|--------|---------------------|
394| `drv` | Derivation | One of `$pkg.components.tests.$test`. |
396For convenience `$pkg.components.tests` are mapped with this function
397to `$pkg.checks`.
399This function is intended for use with `tests` but it should also work
400for `exes` and `benchmarks` if you just want to run them to make sure
401they execute.
403#### subComponentTypes
405Sub-component types identify [components](#component) and are one of:
407 - `sublibs`
408 - `foreignlibs`
409 - `exes`
410 - `tests`
411 - `benchmarks`
413# Project functions
415These functions are included in the `project` return values.
416In the past they also existed within `project.hsPkgs`,
417but have now been removed from there.
419## shellFor
421Create a `nix-shell` [development
422environment](../tutorials/development.md) for developing one or more
423packages with `ghci` or `cabal v2-build` (but not Stack).
425```
426shellFor =
427 { packages, withHoogle ? true, exactDeps ? false, ...}: ...
428```
431| Argument | Type | Description |
432|----------------|------|---------------------|
433| `packages` | Function | Package selection function. It takes a list of [Haskell packages](#haskell-package) and returns a subset of these packages. |
434| `components` | Function | Similar to `packages`, by default all the components of the selected packages are selected. |
435| `additional` | Function | Similar to `packages`, but the selected packages are built and included in `ghc-pkg list` (not just their dependencies). |
436| `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. |
437| `exactDeps` | Boolean | Prevents the Cabal solver from choosing any package dependency other than what are in the package set. |
438| `tools` | Function | AttrSet of tools to make available e.g. `{ cabal = "3.2.0.0"; }` or `{ cabal = { version = "3.2.0.0"; }; }`. If an AttrSet is provided for a tool, the additional arguments will be passed to the function creating the derivation for that tool. So you can provide an `index-state` or a `materialized` argument like that `{ cabal = { version = "3.2.0.0"; index-state = "2020-10-30T00:00:00Z"; materialized = ./cabal.materialized; }; }` for example. You can specify and materialize the version of hoogle used to construct the hoogle index by including something like `{ hoogle = { version = "5.0.17.15"; index-state = "2020-05-31T00:00:00Z"; materialized = ./hoogle.materialized; }`. Uses a default version of hoogle if omitted. |
439| `inputsFrom` | List | List of other shells to include in this one. The `buildInputs` and `nativeBuildInputs` of each will be included using [mkShell](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-mkShell).
440| `crossPlatforms` | Function | Platform selection function for cross compilation targets to support eg. `ps: with ps; [ghcjs mingwW64]` (see nixpkgs lib.systems.examples for list of platform names). |
441| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |
443**Return value**: a derivation
445!!! warning
447 `exactDeps = true` will set the `CABAL_CONFIG` environment variable
448 to disable remote package servers. This is a
449 [known limitation](../dev/removing-with-package-wrapper.md)
450 which we would like to solve. Use `exactDeps = false` if this is a
451 problem.
454## ghcWithPackages
456Creates a `nix-shell` [development
457environment](../tutorials/development.md) including the given
458packages selected from this package set.
460**Parameter**: a package selection function.
462**Return value**: a derivation
464**Example**:
466```
467haskell.haskellPackages.ghcWithPackages (ps: with ps; [ lens conduit ])
468```
470## ghcWithHoogle
472The same as `ghcWithPackages`, except, a `hoogle` command with a
473Hoogle documentation index of the packages will be included in the
474shell.
476[haskell.nix]: https://github.com/input-output-hk/haskell.nix