git.iko.soy/haskell.nix
on 7d94fe2 help sign in
haskell.nix/docs/reference/library.md
177 lines 4.9 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
45Options for building a package. (todo: more info)
47## Component description
49Options for building a component. (todo: more info)
51## Haskell Package
53A derivation which has a `components` attribute. This derivation is
54actually just for the package `Setup.hs` script, and isn't very
55interesting. To actually use the package, look within the components
56structure.
58```
59components = {
60 library = COMPONENT;
61 exes = { NAME = COMPONENT; };
62 tests = { NAME = COMPONENT; };
63 benchmarks = { NAME = COMPONENT; };
64 all = COMPONENT;
66```
68## Component
70## Identifier
72A package identifier is an attrset pair of `name` and `version`.
74## Extras
76## Modules
78# Top-level attributes
80## mkStackPkgSet
82Creates a [package set](#package-set) based on the `pkgs.nix` output
83of `stack-to-nix`.
85```nix
86mkStackPkgSet =
87 { stack-pkgs, pkg-def-extras ? [], modules ? []}: ...
88```
90| Argument | Type | Description |
91|------------------|------|---------------------|
92| `stack-pkgs` | | `import ./pkgs.nix` — The imported file generated by `stack‑to‑nix`. |
93| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
94| `modules` | List of [Modules](#modules) | For overriding the package set. |
96**Return value**: a [`pkgSet`](#package-set)
98## mkCabalProjectPkgSet
100Creates a [package set](#package-set) based on the `pkgs.nix` output
101of `plan-to-nix`.
103```nix
104mkCabalProjectPkgSet =
105 { plan-pkgs, pkg-def-extras ? [], modules ? []}: ...
106```
108| Argument | Type | Description |
109|------------------|------|---------------------|
110| `plan-pkgs` | | `import ./pkgs.nix` — The imported file generated by `plan‑to‑nix`. |
111| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
112| `modules` | List of [Modules](#modules) | For overriding the package set. |
114**Return value**: a [`pkgSet`](#package-set)
116## mkPkgSet
118This is the base function used by both `mkStackPkgSet` and
119`mkCabalProjectPkgSet`.
121**Return value**: a [`pkgSet`](#package-set)
123## snapshots
125This is an attrset of `hsPkgs` packages from Stackage.
127## haskellPackages
129A `hsPkgs` package set
131## nix-tools
133A derivation containing the `nix-tools` [command-line tools](commands.md).
135## callStackToNix
137## callCabalProjectToNix
139## hackage
140## stackage
142## fetchExternal
144## cleanSourceHaskell
146## haskellLib
148# Package-set functions
150These functions exist within the `hsPkgs` package set.
152## shellFor
154Create a `nix-shell` [development
155environment](../user-guide/development.md) *for* developing one or
156more packages.
158```
159shellFor =
160 { packages, withHoogle ? true, ...}: ...
161```
164| Argument | Type | Description |
165|----------------|------|---------------------|
166| `packages` | Function | Package selection function. It takes a list of [Haskell packages](#haskell-package) and returns a subset of these packages. |
167| `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. |
168| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |
170**Return value**: a derivation
172## ghcWithPackages
174## ghcWithHoogle
177[haskell.nix]: https://github.com/input-output-hk/haskell.nix