Nix and Haskell in production

This guide documents how I use Nix for Haskell development. Feel free to open
issues or pull requests if you would like to contribute or suggest improvements

The purpose of this project is to support two Haskell workflows:

• Workflow #1: Nix provisions the development environment
  • Nix provides all dependencies and the Haskell toolchain
  • You still build the root project using cabal (overview, user's guide)
  • This approach is ideal for development as it supports incremental builds
• Workflow #2: Nix builds the root project for you
  • This approach is ideal for continuous integration (especially Hydra)

The emphasis of this guide is to be as robust as possible and gracefully handle
writing Haskell projects at scale. Some of the suggestions in this guide might
be overkill for a small Haskell project but are essential when managing multiple
private Haskell projects across a team of developers.

This guide is based partly on
the Haskell section of the nixpkgs manual
and partly on experience using Nix and Haskell in production at
Awake Security.

Background

Nix is not a cabal replacement and Nix actually complements cabal quite
well. Nix is much more analogous to a stack replacement. stack does
provide some support for Nix integration, but this document does not cover that.
Instead, this document describes how to use Nix in conjunction with cabal for
Haskell development

The main benefits of using Nix over stack are:

• Binary caches

  Nix lets you download precompiled Hackage packages whereas stack compiles
  them on your computer the first time you depend on them

• Space efficiency

  stack creates a copy of each package for each resolver. This means that
  if you have two projects with different resolvers then they will not use
  the same copy of shared dependencies

• Generality

  Nix is a language-independent build tool. This means you can use Nix to
  also build and customize non-Haskell dependencies (like gtk). This
  uniform language simplifies build tooling and infrastructure.

• Larger ecosystem

  Nix provides a large ecosystem of tools that integrate with anything that
  Nix can build, such as Hydra (continuous integration), NixOS (an operating
  system), and NixOps (a deploy tool)

• Flexibility

  Nix is a powerful tool in the hands of advanced users. You can make very
  deep and sweeping changes to your toolchain, such as recompiling everything
  with security hardening

The main disadvantage of using Nix over stack are:

• Verbosity

  Nix derivations for Haskell projects are significantly more complex than
  their corresponding stack.yaml files. The release.nix files in this
  repository are the Nix analog of a stack.yaml file and you can see for
  yourself the increase in complexity as the examples progress in difficulty.

• Poor error messages

  Nix is an untyped language with no special Haskell integration, so error
  messages are unhelpful

• Nix cannot incrementally compile Haskell libraries

  Note that you can still use Nix to provision a development environment and
  incrementally compile a Haskell package using cabal. However, if you use Nix
  to build the package then Nix will build the package from scratch for every
  minor change. In theory, this could be fixed to have Nix directly support
  incremental Haskell builds but this has not been done yet.

• Worse user experience

  Nix does not provide many conveniences that stack does such as
  bootstrapping new projects or "file watch"

Both Nix and stack use curated package sets instead of version bounds for
dependency management. stack calls these package sets "resolvers" whereas
Nix calls these package sets "channels". Nix provides stable channels with
names like NixOS-18.09 (analogous to stack's LTS releases) and then an
unstable channel named nixpkgs-unstable (analogous to stack's nightly
releases)

Related guides

• Nix Haskell Monorepo Tutorial -
  Guide on how to scale Nix development to a larger repository containing all of
  a company's internally-developed Haskell packages

Related tools

Before continuing, I'd like to mention some other tools for mixing Haskell with
Nix:

• tinc - this uses
  cabal's solver to select which Haskell packages to use instead of the
  curated Haskell package set from nixpkgs
• styx - This tool provides a stack-like
  interface to managing Haskell dependencies using Nix
• haskell-overridez -
  Tool that automates dependency management as described in this guide

Setup

Before you begin, you must install Nix if you haven't already:

$ curl -L https://nixos.org/nix/install | sh

You must also install cabal2nix and nix-prefetch-git:

$ nix-env --install cabal2nix
$ nix-env --install nix-prefetch-git

You also need to install cabal if you haven't done so already. You can either
use your installed cabal or you can use nix to install cabal for you:

$ nix-env --install cabal-install

Make sure that you have a fairly recent version of cabal installed since these
examples will use GHC 8 which requires version 1.24 or later of cabal. You
can check what version you have installed by running:

$ cabal --version

Finally, run cabal update if you haven't done so already

Organization

This tutorial is split into several tutorial projects in the project*/
subdirectories. Read the README.md file in each subdirectory in
order to follow the tutorial:

• Project 0 - Nix basics
• Project 1 - Dependency management
• Project 2 - Non-Haskell dependencies
• Project 3 - Customizing Haskell projects
• Project 4 - Advanced dependency management