[Haskell.nix][] contains a library of functions for creating buildable
package sets from their Nix expression descriptions. The library is
what you get when importing [Haskell.nix][]. It might be helpful to
load the library in the [Nix REPL](../user-guide.md#using-nix-repl) to
test things.

# Types

## Package Set

The result of `mkPkgSet`. This is an application of the NixOS module
system.

```
{
  options = { ... };
  config = {
    hsPkgs = { ... };
    packages = { ... };
    compiler = {
      version = "X.Y.Z";
      nix-name = "ghcXYZ";
      packages = { ... };
    };
  };
}
```

| Attribute      | Type | Description                                         |
|----------------|------|-----------------------------------------------------|
| `options` | Module options | The combination of all options set through the `modules` argument passed to `mkPkgsSet`. |
| `config` |  | The result of evaluating and applying the `options` with [Haskell.nix][] |
| `.hsPkgs` | Attrset of [Haskell Packages](#haskell-package) | Buildable packages, created from `packages` |
| `.packages` | Attrset of [Haskell Package descriptions](#haskell-package-descriptions) | Configuration for each package in `hsPkgs` |
| `.compiler` | Attrset | |



## Haskell Package description

Options for building a package. (todo: more info)

## Component description

Options for building a component. (todo: more info)

## Haskell Package

A derivation which has a `components` attribute. This derivation is
actually just for the package `Setup.hs` script, and isn't very
interesting. To actually use the package, look within the components
structure.

```
components = {
  library = COMPONENT;
  exes = { NAME = COMPONENT; };
  tests = { NAME = COMPONENT; };
  benchmarks = { NAME = COMPONENT; };
  all = COMPONENT;
}
```
  
## Component

## Identifier

A package identifier is an attrset pair of `name` and `version`.

## Extras

## Modules

# Top-level attributes

## mkStackPkgSet

Creates a [package set](#package-set) based on the `pkgs.nix` output
of `stack-to-nix`.

```nix
mkStackPkgSet =
    { stack-pkgs, pkg-def-extras ? [], modules ? []}: ...
```

| Argument         | Type | Description         | 
|------------------|------|---------------------|
| `stack-pkgs`     |  | `import ./pkgs.nix` — The imported file generated by `stack‑to‑nix`. |
| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
| `modules` | List of [Modules](#modules) | For overriding the package set. |

**Return value**: a [`pkgSet`](#package-set)

## mkCabalProjectPkgSet

Creates a [package set](#package-set) based on the `pkgs.nix` output
of `plan-to-nix`.

```nix
mkCabalProjectPkgSet =
    { plan-pkgs, pkg-def-extras ? [], modules ? []}: ...
```

| Argument         | Type | Description         | 
|------------------|------|---------------------|
| `plan-pkgs`     |  | `import ./pkgs.nix` — The imported file generated by `plan‑to‑nix`. |
| `pkg‑def‑extras` | List of [Extras](#extras) | For overriding the package set. |
| `modules` | List of [Modules](#modules) | For overriding the package set. |

**Return value**: a [`pkgSet`](#package-set)

## mkPkgSet

This is the base function used by both `mkStackPkgSet` and
`mkCabalProjectPkgSet`.

**Return value**: a [`pkgSet`](#package-set)

## snapshots

This is an attrset of `hsPkgs` packages from Stackage.

## haskellPackages

A `hsPkgs` package set

## nix-tools

A derivation containing the `nix-tools` [command-line tools](commands.md).

## callStackToNix

## callCabalProjectToNix

## hackage
## stackage

## fetchExternal

## cleanSourceHaskell

## haskellLib

# Package-set functions

These functions exist within the `hsPkgs` package set.

## shellFor

Create a `nix-shell` [development
environment](../user-guide/development.md) *for* developing one or
more packages.

```
shellFor =
    { packages, withHoogle ? true, ...}: ...
```


| Argument       | Type | Description         | 
|----------------|------|---------------------|
| `packages`     | Function | Package selection function. It takes a list of [Haskell packages](#haskell-package) and returns a subset of these packages. |
| `withHoogle` | Boolean | Whether to build a Hoogle documentation index and provide the `hoogle` command. |
| `{ ... }` | Attrset | All the other arguments are passed to [`mkDerivation`](https://nixos.org/nixpkgs/manual/#sec-using-stdenv). |

**Return value**: a derivation

## ghcWithPackages

## ghcWithHoogle


[haskell.nix]: https://github.com/input-output-hk/haskell.nix