You'll need to get Nix. The installer will create your Nix store in the /nix/ directory, where all build artifacts and their dependencies will be stored. It will also link the Nix executables like nix-env, nix-build and nix-shell into your PATH. Nix will manage all other PostgREST dependencies from here on out. To clean up older build artifacts from the /nix/store, you can run nix-collect-garbage.

Building PostgREST

To build PostgREST from your local checkout of the repository, run:

nix-build --attr postgrest

This will create a result directory that contains the PostgREST binary at result/bin/postgrest. The --attr parameter (or short: -A) tells Nix to build the postgrest attribute from the Nix expression it finds in our default.nix (see below for details). Nix will take care of getting the right GHC version and all the build dependencies.

Developing

A development environment for PostgREST is available with nix-shell. The following command will put you into a new shell that has GHC and Cabal on the PATH:

nix-shell

Within nix-shell, you can run Cabal commands as usual. You can also run stack with the --nix option, which causes stack to pick up the non-Haskell dependencies from the same pinned Nixpkgs version that the Nix builds use.

Tour

The following is not required for working on PostgREST with Nix, but it will give you some more background and details on how it works.

`default.nix`

default.nix is our 'respository expression' that pulls all the pieces that we define with Nix together. It returns a set (like a dict in other programming languages), where each attribute is a derivation that Nix knows how to build, like the postgrest attribute from earlier.

Internally, our default.nix uses the pkgs.callPackage function to import the modules that we defined in the nix directory. It automatically passes the arguments those modules require if they are available in pkgs (this means that pkgs is defined in terms of itself, better not to think too much about that).

We also use default.nix to load our pinned version of the nixpkgs repository. This set of packages will always be the same, independently from where or when you use it. The pinned version can be upgraded with the small nixpkgs-upgrade utility. Running nixpkgs-upgrade > nix/nixpkgs-version.nix in nix-shell will upgrade the pinned version to the latest nixpkgs-unstable version.

`shell.nix`

shell.nix defines an environment in which PostgREST can be built and developed. It extends the build enviroment from our postgrest attribute with useful utilities that will be put on the PATH in nix-shell.

`nix/overlays`

Our overlays to the Nix package set are defined here. They allow us to tweak our pkgs in default.nix by adding new packages or overriding existing ones.