Pretty development guide

1. Setting up a development environment
2. Building
3. Tests
- 3.1. Unit tests
- 3.2. Integration tests
4. Source code formatting
5. Documentation generation

These are instructions for how to perform common tasks for Pretty development.

1 Setting up a development environment

Pretty depends on a number of tools for its development – for tasks such as documentation generation and editor enhancements – that are not required for just installing it.

The Nix package manager ensures that all of Pretty's dependencies (including the C++ compiler) are precisely "pinned" to specific versions in a reproducible way. Pretty uses an upcoming features of Nix called "flakes", so a version of nix with support for flakes is required.

The following command will start a new Bash shell with all of Pretty's dependencies available:

$ nix develop

A tool called direnv can automate this process so that the environment gets updated whenever the current working directory changes. To enable this for Pretty, rename the included template:

$ cp envrc.template .envrc
$ direnv allow

2 Building

Pretty uses CMake as its build system.

First, create a separate build directory (typically called build):

$ mkdir build

Then configure the project (here, we're building with debugging symbols, with support for editor tooling, and with the Ninja build system):

$ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=yes -DCMAKE_BUILD_TYPE=Debug -G Ninja $build_dir

Finally, compile:

$ ninja -C $build_dir

3 Tests

There are two kinds of kinds of tests in Pretty.

3.1 Unit tests

First, ensure the build is configured with tests enabled:

$ cmake -DPretty_TESTS=yes $build_dir

You can either run the test target via

# ninja -C $build_dir test

or invoke ctest directly

$ cd $build_dir
$ ctest --output-on-failure

3.2 Integration tests

There are two interesting integration tests in Pretty.

The first test compiles the Haskell implementation of Wadler's paper using GHC and runs it against a fixed input. The same input is fed to Pretty. The test passes if the output from both implementations is the same.

The second test installs Pretty to the file system and ensures that a client can successfuly link against it via CMake. This test is important because CMake can be tricky.

These tests are executed using Nix. To run both tests:

$ nix flake check

4 Source code formatting

Pretty's code is formatted using ClangFormat. To automatically format all files in-place, execute

$ make format

5 Documentation generation

The documentation you're reading now is generated by Emacs from org-mode files:

$ make doc

To generate publishable documentation (with a version number), use the Nix derivation:

$ nix build .#doc

(The HTML files are in the result directory.)