Developer's guide

Build

To install from source, you'll need to install Rust and Cargo. Follow the instructions on the Rust installation page. Then, get the source:

git clone https://github.com/langston-barrett/zbr
cd zbr

Finally, build everything:

cargo build --release

You can find binaries in target/release. Run tests with cargo test.

Docs

HTML documentation can be built with mdBook:

cd doc
mdbook build

Format

All code should be formatted with rustfmt. You can install rustfmt with rustup like so:

rustup component add rustfmt

and then run it like this:

cargo fmt

Lint

All code should pass Clippy. You can install Clippy with rustup like so:

rustup component add clippy

and then run it like this:

cargo clippy --workspace -- --deny warnings

Profile

TODO

Warnings

Certain warnings are disallowed in the CI build. You can reproduce the behavior of the CI build by running cargo check, cargo build, or cargo test like so:

env RUSTFLAGS="@$PWD/rustc-flags" cargo check

Using a flag file for this purpose achieves several objectives:

• It frictionlessly allows code with warnings during local development
• It makes it easy to reproduce the CI build process locally
• It makes it easy to maintain the list of warnings
• It maintains forward-compatibility with future rustc warnings
• It ensures the flags are consistent across all crates in the project

This flag file rejects all rustc warnings by default, as well as a subset of allowed-by-default lints. The goal is to balance high-quality, maintainable code with not annoying developers.

To allow a lint in one spot, use:

#![allow(unused)]
fn main() {
#[allow(name_of_lint)]
}

To enable these warnings on a semi-permanent basis, create a [Cargo configuration file][cargo-conf]:

mkdir .cargo
printf "[build]\nrustflags = [\"@${PWD}/rustc-flags\"]\n" > .cargo/config.toml