git.iko.soy/haskell.nix
on fe44ce2 help sign in
haskell.nix/docs/reference/library.md
322 lines 9.7 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.
286```
287shellFor =
288 { packages, withHoogle ? true, ...}: ...
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| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |
298**Return value**: a derivation
300## ghcWithPackages
302Creates a `nix-shell` [development
303environment](../user-guide/development.md) including the given
304packages selected from this package set.
306**Parameter**: a package selection function.
308**Return value**: a derivation
310**Example**:
312```
313haskell.haskellPackages.ghcWithPackages (ps: with ps; [ lens conduit ])
314```
316## ghcWithHoogle
318The same as `ghcWithPackages`, except, a `hoogle` command with a
319Hoogle documentation index of the packages will be included in the
320shell.
322[haskell.nix]: https://github.com/input-output-hk/haskell.nix