git.iko.soy/haskell.nix
on f4cc5eb help sign in
haskell.nix/docs/reference/library.md
173 lines 4.6 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
9## Package Set
11The result of `mkPkgSet`. This is an application of the NixOS module
12system.
14```
16 options = { ... };
17 config = {
18 hsPkgs = { ... };
19 packages = { ... };
20 compiler = {
21 version = "X.Y.Z";
22 nix-name = "ghcXYZ";
23 packages = { ... };
24 };
25 };
27```
29| Attribute | Type | Description |
30|----------------|------|-----------------------------------------------------|
31| `options` | Module options | The combination of all options set through the `modules` argument passed to `mkPkgsSet`. |
32| `config` | | The result of evaluating and applying the `options` with [Haskell.nix][] |
33| `.hsPkgs` | Attrset of [Haskell Packages](#haskell-package) | Buildable packages, created from `packages` |
34| `.packages` | Attrset of [Haskell Package descriptions](#haskell-package-descriptions) | Configuration for each package in `hsPkgs` |
35| `.compiler` | Attrset | |
39## Haskell Package description
41Options for building a package. (todo: more info)
43## Component description
45Options for building a component. (todo: more info)
47## Haskell Package
49A derivation which has a `components` attribute. This derivation is
50actually just for the package `Setup.hs` script, and isn't very
51interesting. To actually use the package, look within the components
52structure.
54```
55components = {
56 library = COMPONENT;
57 exes = { NAME = COMPONENT; };
58 tests = { NAME = COMPONENT; };
59 benchmarks = { NAME = COMPONENT; };
60 all = COMPONENT;
62```
64## Component
66## Identifier
68A package identifier is an attrset pair of `name` and `version`.
70## Extras
72## Modules
74# Top-level attributes
76## mkStackPkgSet
78Creates a [package set](#package-set) based on the `pkgs.nix` output
79of `stack-to-nix`.
81```nix
82mkStackPkgSet =
83 { stack-pkgs, pkg-def-extras ? [], modules ? []}: ...
84```
86| Argument | Type | Description |
87|------------------|------|---------------------|
88| `stack-pkgs` | | `import ./pkgs.nix` — The imported file generated by `stack‑to‑nix`. |
89| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
90| `modules` | List of [Modules](#modules) | For overriding the package set. |
92**Return value**: a [`pkgSet`](#package-set)
94## mkCabalProjectPkgSet
96Creates a [package set](#package-set) based on the `pkgs.nix` output
97of `plan-to-nix`.
99```nix
100mkCabalProjectPkgSet =
101 { plan-pkgs, pkg-def-extras ? [], modules ? []}: ...
102```
104| Argument | Type | Description |
105|------------------|------|---------------------|
106| `plan-pkgs` | | `import ./pkgs.nix` — The imported file generated by `plan‑to‑nix`. |
107| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
108| `modules` | List of [Modules](#modules) | For overriding the package set. |
110**Return value**: a [`pkgSet`](#package-set)
112## mkPkgSet
114This is the base function used by both `mkStackPkgSet` and
115`mkCabalProjectPkgSet`.
117**Return value**: a [`pkgSet`](#package-set)
119## snapshots
121This is an attrset of `hsPkgs` packages from Stackage.
123## haskellPackages
125A `hsPkgs` package set
127## nix-tools
129A derivation containing the `nix-tools` [command-line tools](commands.md).
131## callStackToNix
133## callCabalProjectToNix
135## hackage
136## stackage
138## fetchExternal
140## cleanSourceHaskell
142## haskellLib
144# Package-set functions
146These functions exist within the `hsPkgs` package set.
148## shellFor
150Create a `nix-shell` [development
151environment](../user-guide/development.md) *for* developing one or
152more packages.
154```
155shellFor =
156 { packages, withHoogle ? true, ...}: ...
157```
160| Argument | Type | Description |
161|----------------|------|---------------------|
162| `packages` | Function | Package selection function. It takes a list of [Haskell packages](#haskell-package) and returns a subset of these packages. |
163| `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. |
164| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |
166**Return value**: a derivation
168## ghcWithPackages
170## ghcWithHoogle
173[haskell.nix]: https://github.com/input-output-hk/haskell.nix