All `haskell.packages.*` package sets use the same package descriptions and the same sets
of versions by default. There are however GHC version specific override `.nix`
files to loosen this a bit.

### Dependency resolution {#haskell-dependency-resolution}

Normally when you build Haskell packages with `cabal-install`, `cabal-install`
does dependency resolution. It will look at all Haskell package versions known
on Hackage and tries to pick for every (transitive) dependency of your build
exactly one version. Those versions need to satisfy all the version constraints
given in the `.cabal` file of your package and all its dependencies.

The [Haskell builder in nixpkgs](#haskell-mkderivation) does no such thing.
It will take as input packages with names off the desired dependencies
and just check whether they fulfill the version bounds and fail if they don’t
(by default, see `jailbreak` to circumvent this).

The `haskellPackages.callPackage` function does the package resolution.
It will, e.g., use `haskellPackages.aeson`which has the default version as
described above for a package input of name `aeson`. (More general:
`<packages>.callPackage f` will call `f` with named inputs provided from the
package set `<packages>`.)
While this is the default behavior, it is possible to override the dependencies
for a specific package, see
[`override` and `overrideScope`](#haskell-overriding-haskell-packages).

### Limitations {#haskell-limitations}

Our main objective with `haskellPackages` is to package Haskell software in
nixpkgs. This entails some limitations, partially due to self-imposed
restrictions of nixpkgs, partially in the name of maintainability:

* Only the packages built with the default compiler see extensive testing of the
  whole package set. For other GHC versions only a few essential packages are
  tested and cached.
* As described above we only build one version of most packages.

The experience using an older or newer packaged compiler or using different
versions may be worse, because builds will not be cached on `cache.nixos.org`
or may fail.

Thus, to get the best experience, make sure that your project can be compiled
using the default compiler of nixpkgs and recent versions of its dependencies.

A result of this setup is, that getting a valid build plan for a given
package can sometimes be quite painful, and in fact this is where most of the
maintenance work for `haskellPackages` is required. Besides that, it is not
possible to get the dependencies of a legacy project from nixpkgs or to use a
specific stack solver for compiling a project.

Even though we couldn’t use them directly in nixpkgs, it would be desirable
to have tooling to generate working Nix package sets from build plans generated
by `cabal-install` or a specific Stackage snapshot via import-from-derivation.
Sadly we currently don’t have tooling for this. For this you might be
interested in the alternative [haskell.nix] framework, which, be warned, is
completely incompatible with packages from `haskellPackages`.

<!-- TODO(@maralorn) Link to package set generation docs in the contributors guide below. -->

### GHC Deprecation Policy {#ghc-deprecation-policy}

We remove GHC versions according to the following policy:

#### Major GHC versions {#major-ghc-deprecation}

We keep the following GHC major versions:
1. The current Stackage LTS as the default and all later major versions.
2. The two latest major versions older than our default.
3. The currently recommended GHCup version and all later major versions.

Older GHC versions might be kept longer, if there are in-tree consumers. We will coordinate with the maintainers of those dependencies to find a way forward.

#### Minor GHC versions {#minor-ghc-deprecation}

Every major version has a default minor version. The default minor version will be updated as soon as viable without breakage.

Older minor versions for a supported major version will only be kept, if they are the last supported version of a major Stackage LTS release.