Using GHC pre-releases: A tutorial

Ben Gamari - 2019-07-07

The user testing period for GHC pre-releases is an important part of the GHC release process. However, it has historically been difficult for users to meaningfully test pre-release compilers against real-world projects due to interface changes in base and related libraries.

The head.hackage repository attempts to ease this testing process by providing infrastructure and a common place for users to provide patches for pre-release compilers. Recently we have been working on further automating this infrastructure in the hope that further reducing the friction to contribution will increase usage. This automation includes:

  • continuous integration testing of patches against GHC HEAD
  • automated preparation of a Hackage repository for convenient use by users

This post will walk through how an end user can use a GHC prerelease (either alpha or CI snapshot) to build their package using cabal new-build.

Installing the pre-release

Let’s start by installing a GHC pre-release binary distribution. There are several places from which we could get such a distribution:

For the sake of staying on the bleeding edge we will rather opt to use a binary distribution snapshot from CI. For this we will use Matthew Pickering’s ghc-artefact-nix; this is an appealing option as it is agnostic to the host operating system.


We will assume a Debian 9 environment and will therefore use a binary distribution from the validate-x86_64-linux-deb9-dwarf CI job:

We can test this with “Hello World”:

Setting up head.hackage

As noted earlier, we will use the head.hackage patch-set in conjunction with cabal v2-build to build the handy ghc-events-analyze utility.

First we can start by just checking out ghc-events-analyze:

We can now setting up our cabal.project file to use our pre-release compiler:

Next we will install the project file fragment containing the head.hackage repository definition (you can also view this fragment on the head.hackage reference page):

Finally, we tell cabal to update its project-local pacakge index:

Now we can go ahead and build our first package:

We can now drop into ghci and use our new library:

We would start by
cloning the `head.hackage` repository:

$ git clone
$ cd head.hackage
$ git checkout -b fix-xxx

Next we fetch and unpack xxx using the handy patch-tool script:

patch-tool will fetch the latest version of xxx from Hackage, extract it to the packages/xxx directory and initialize a fresh git repository in that working directory to ensure that we can later easily generate a patch with our changes.

We can now go ahead and make the necessary changes to xxx to address the build errors we previously encountered.

When ready we can generate a patch:

Finally we can push our branch to a personal GitHub fork and open a pull request with our changes.


Thanks to the cabal-install developers for all of their working in putting in place the pieces that make head.hackage possible. Additionally, thanks to Herbert Valerio Riedel for kick-starting the patch-set and its infrastructure.