Fang development guide

1. Setting up a development environment
2. Building
3. Testing
4. Source-code formatting
5. Interactive REPL
6. Documentation generation
- 6.1. API documentation
- 6.2. Other documents
7. Release check-list

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

1 Setting up a development environment

Fang 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 Fang's dependencies (including the OCaml compiler) are precisely "pinned" to specific versions in a reproducible way. Fang 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 Fang'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 Fang, rename the included template:

$ cp envrc.template .envrc
$ direnv allow

2 Building

Fang uses the Dune build system for OCaml. To build the entire repository:

$ dune build

It's also possible to execute either fangc or fangu such that it's always up-to-date with its sources:

$ dune exec fangc < foo.tig

3 Testing

Fang has a number of tests.

Unit and integration tests are executed via

$ dune test

Many of Fang's tests compare its output to predefined reference output. When something in Fang changes so that the output doesn't match, dune test will print out a diff. If the changes are correct (so that a new reference should be saved), then the files can updated:

# Change code.
# ..

# Test.
$ dune test

# Accept changes.
$ dune promote

Fang also has built-in "distribution" tests to ensure that it can be installed with the OCaml package manager. These tests use containers for isolation, and they take a few minutes.

$ make test-dist

4 Source-code formatting

Fang uses an automatic code formatter for both OCaml source code and also Dune files. To format all files:

$ make format

5 Interactive REPL

It's possible to start an interactive OCaml REPL ("top-level", on OCaml parlance) with all of Fang's library code accessible:

$ dune utop

6 Documentation generation

There are two kinds of Fang documentation: API documentation for the underlying OCaml library, and "human-friendly" documentation like you're currently reading.

6.1 API documentation

Documentation is automatically generated from annotated .mli files via

$ dune build @doc

However, sometimes the paths of identifiers are longer than they could be (see this issue) so Fang post-processes the output. To build this post-processed output, execute

$ make doc-api

(This approach to post-processing is adopted from the Lambdasoup project.)

After it's been generated, the documentation is available starting at _build/default/_doc/_html/fang/index.html.

6.2 Other documents

Overview documentation is written in org-mode and exported to HTML using Emacs itself.

Generate these documents via:

$ make doc-human

7 Release check-list

[ ] make test-license
[ ] make test-flake
[ ] make test-dist
[ ] Tag release
[ ] make dist and upload to S3
[ ] Update published API documents