Developing RCL¶

This chapter explains the tools and workflows involved in hacking on RCL. To get started, clone the repository from one of the two mirrors:

git clone https://codeberg.org/ruuda/rcl.git
git clone https://github.com/ruuda/rcl.git

Building¶

RCL is written in Rust and builds with Cargo:

cargo build
target/debug/rcl --help

See the building chapter for more details and alternative build configurations.

CI and automated tests¶

Almost all of the checks that are part of the RCL development process are automated, and included in the Nix flake. These checks are verified on CI by Garnix, but you can run them locally as well:

nix flake check

This means that you can reproduce and debug any CI run locally.

While it is convenient to be able to run all checks in one command, if you know what parts of RCL you changed, you can run just the relevant checks. They are listed in the section below.

Development environment¶

For the tools used for development, the Nix flake includes a devshell with the right version of development dependencies (Python, MkDocs, Tree-sitter, ets.) that you can enter with:

nix develop --command $SHELL

Sourcing your tools elsewhere (e.g. your system package manager) will probably work, but only the Nix flake is continuously tested on CI.

Individual checks¶

Run the golden tests:

cargo build
golden/run.py

View coverage of the golden tests:

nix build .#coverage --out-link result
xdg-open result/index.html

Run unit tests and lints:

cargo test --workspace
cargo clippy --workspace

Typecheck Python sources:

mypy --strict --exclude pyrcl .
mypy --strict pyrcl

Autoformat Rust, Python, and RCL code:

cargo fmt
black .
fd . --extension .rcl --exclude golden --exec-batch rcl format --in-place

Build and preview the manual:

mkdocs serve

Build crate documentation and check for issues:

RUSTFLAGS="--deny warnings" cargo doc --no-deps --workspace

Fuzz tests¶

After implementing a feature, run the fuzzers to ensure the code still respects all invariants and is free of crashes. See the fuzzing section in the testing chapter.