This blog post was inspired by the work of Gabriel Gonzalez at haskell-nix github repository which has a lot of practical information on how to structure a Haskell project in NixOS. Here I will show my own view on a typical Haskell project structure in NixOS taking into account Gabriel’s work.

I would encourage everyone interested to fork haskell-nix and go through Gabriel’s tutorial. That helped me understand some of the issues I was not aware before.

Requirements

  1. default.nix must not change other than with $ cabal2nix . > default.nix
  2. shell.nix must be able to bring developer environment with Hoogle server that will serve documentation for all dependencies used in Cabal file
  3. release.nix must declare at least two packages - one with dynamically linked dependencies, and another - with statically linked dependencies
  4. release.nix must produce output expected by Hydra build system
  5. shell.nix as well as release.nix must use pinned nixpkgs to ensure reproducibility of builds
  6. shell.nix as well as release.nix must be open for choosing version of ghc compiler

Generate default.nix

This is mostly straightforward:

1

$ cabal2nix . > default.nix

Pinning nixpkgs

To ensure reproducible builds it is important to fixate on a specific version of nixpkgs. Let’s now generate nixpkgs.json that will be used later in shell.nix and release.nix by issuing the following command:

1
2
3
4

$ nix-prefetch-git --no-deepClone --quiet \
    https://github.com/NixOS/nixpkgs.git \
    6484eac5b2e38490724d9df3079e736605c7eeb6 > nixpkgs.json
$ cat nixpkgs.json

This should produce the following output:

1
2
3
4
5
6
7

{
  "url": "https://github.com/NixOS/nixpkgs.git",
  "rev": "6484eac5b2e38490724d9df3079e736605c7eeb6",
  "date": "2018-01-04T09:54:52+01:00",
  "sha256": "1w3ca4jzkksbdn7vhnc9h06mp3m39b37bwnszqs09jzgd4smhykl",
  "fetchSubmodules": true
}

Building shell.nix

It is possible to generate shell.nix with $ cabal2nix --shell . > shell.nix, but it is not recommended as we are going to make sure we meet the requirement of running a Hoogle server locally with all the used dependencies.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{ compiler ? "ghc822"
, withHoogle ? true
}:

let
  bootstrap = import <nixpkgs> {};
  nixpkgs = builtins.fromJSON (builtins.readFile ./nixpkgs.json);
  src = bootstrap.fetchFromGitHub {
    owner = "NixOS";
    repo  = "nixpkgs";
    inherit (nixpkgs) rev sha256;
  };
  pkgs = import src {};
  f = import ./default.nix;
  packageSet = pkgs.haskell.packages.${compiler};
  hspkgs = (
    if withHoogle then
      packageSet.override {
        overrides = (self: super: {
          ghc = super.ghc // { withPackages = super.ghc.withHoogle; };
          ghcWithPackages = self.ghc.withPackages;
        });
      }
      else packageSet
  );
  drv = hspkgs.callPackage f {};
in
  if pkgs.lib.inNixShell then drv.env else drv

Then in order to start your local Hoogle server:

1
2

$ nix-shell
shell$ hoogle server --port=8080 --local --haskell

Then navigate to 127.0.0.1:8080 in order to test if documentation server is running.

Building release.nix

release.nix also needs to use pinned version of nixpkgs. It also declares two haskell packages - one package-name and another package-name-static - dynamically and statically linked versions respectively. It also produces a set of derivations as a result which is what Hydra expects.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

{ compiler ? "ghc822" }:

let
  bootstrap = import <nixpkgs> {};
  nixpkgs = builtins.fromJSON (builtins.readFile ./nixpkgs.json);
  src = bootstrap.fetchFromGitHub {
    owner = "NixOS";
    repo  = "nixpkgs";
    inherit (nixpkgs) rev sha256;
  };
  config = {
    packageOverrides = pkgs: rec {
      haskell = pkgs.haskell // {
        packages = pkgs.haskell.packages // {
          "${compiler}" = pkgs.haskell.packages."${compiler}".override {
            overrides = hspkgsNew: hspkgsOld: rec {
              package-name = hspkgsNew.callPackage ./default.nix {};
              package-name-static =
                pkgs.haskell.lib.overrideCabal
                  (pkgs.haskell.lib.justStaticExecutables (hspkgsNew.callPackage ./default.nix {}))
                  (oldDerivation: {
                    configureFlags = [
                      "--ghc-option=-optl=-static"
                      "--ghc-option=-optl=-pthread"
                      "--ghc-option=-optl=-L${pkgs.gmp5.static}/lib"
                      "--ghc-option=-optl=-L${pkgs.zlib.static}/lib"
                      "--ghc-option=-optl=-L${pkgs.glibc.static}/lib"
                    ];
                  });
            };
          };
        };
      };
    };
  };
  pkgs = import src { inherit config; };
in
{ package-name = pkgs.haskell.packages.${compiler}.package-name;
  package-name-static = pkgs.haskell.packages.${compiler}.package-name-static;
}

Make sure to rename package-name with your project name.

Then building the project locally ends up being as simple as:

1

$ nix-build release.nix

And installing dynamically linked package with $ nix-env -i ./result. Or statically linked package with $ nix-env -i ./result-2.

Make sure you understand that package-name-static package is statically linked against current version of glibc used in the current system. This has some consequences that are not necessarily obvious. For example it will not necessarily work when packaged as alpine docker image. Reason being that alpine images are built using musl C-library instead of glibc, and since your package-name-static has glibc statically linked it won’t be possible to always properly run it. The worst part about it is that it will only fail in run-time, e.g. when resolving DNS for establishing a TCP connection. I am sure there will be some other issues too.