Developing Primer

With Nix

We use Nix flakes to develop Primer, so most of our developer documentation assumes you've got a working Nix installation with flakes support enabled, and that you're running any given commands in the project's nix develop shell.

Our flake supports both x86_64-linux and aarch64-darwin systems. Adding support for other common architectures should be straightforward, but we don't currently have the CI resources to support them. Both x86_64-darwin and aarch64-linux have been known to work in the past. Please let us know if you'd like to contribute, but your development platform of choice is not included in our flake.

For faster Nix builds of our project, assuming you're using one of our supported systems, you can make use of our public Cachix cache by adding the following to your Nix config:

nix.settings.substituters = [
  "https://hackworthltd.cachix.org"
];
nix.settings.trusted-public-keys = [
  "hackworthltd.cachix.org-1:0JTCI0qDo2J+tonOalrSQP3yRNleN6bQucJ05yDltRI="
];

Note that, out of an abundance of caution, we only push continuous integration (CI) build artifacts from this project to the public Cachix cache upon merges to the project's main branch. Build artifacts generated by our CI when building GitHub pull requests (PR's) are not cached in the public cache. This does mean that there may be a slight delay between when a PR is merged to main and when its build artifacts are available in the cache.

Without Nix

You can choose to forego Nix and build the provided Cabal projects without it, assuming you have supported versions of GHC and Cabal in your PATH. However, in order to run some of Primer's tests, you'll need additional bespoke tools that are provided automatically by the nix develop shell. These tests will likely fail if they're run locally but not from within the Nix shell.

We'll make a best-effort attempt to ensure that the most common development workflows are supported without Nix, or at least documented, but please note that we don't have the maintainer resources to provide much support if you run into problems in non-Nix environments.

On Windows

We've never attempted to build or run this implementation of Primer on any version of Windows, and we don't have any plans to support it. You may have some success with NixOS on WSL, but we don't have the resources to provide any support for this environment.

Makefile targets

For interactive development workflows, both with and without Nix, we provide some convenient Makefile targets from the repository's top level directory. For example:

• make runs cabal build all.

• make test runs cabal test all.

• make bench runs cabal bench all.