Useful Commands

The Rust toolchain provides a number of useful commands that it is worth being aware of.

Note: The following command should all support --help for more information.

Build

The default way to build GWR.

cd gwr/
cargo build

Or cargo build --release to create a release binary.

A quicker version of the command while you are developping is:

cargo check

This runs all the commands needed to compile the code and report errors without actually producing the binaries.

Open the Documentation

The GWR libraries and APIs are documented using rustdoc. The documentation can be built and opened with:

cargo doc-gwr --open

The documentation can also be generated to include private items, which can be useful when developing GWR packages, by running:

cargo doc-gwr-dev --open

Run the Tests

This command runs all the tests, including compiling and running any snippets in the documentation.

cargo test

Run the Benchmarks

There are a number of benchmarks that have been written to be able to understand the impact of changes on the performance of core components within the engine.

cargo bench

Formatting the Code

There is no need to manually format your code as the Rust tools provide a tool for this that keeps all of the codebase in a consistent format.

This is usually be done using the stable toolchain:

cargo fmt

But for developers of the GWR packages use of the nightly toolchain is required:

cargo +nightly fmt

Helper tools

The clippy tool provides some static analysis tools that help to highlight redundant or not rust-like code that should be refactored:

cargo clippy

The GWR workspace provides an alias that runs clippy with additional lint groups enabled, which is used by the git hooks and CI system:

cargo clippy-strict

Expand

In order to see the pre-processed output the expand tool can be used. It first needs to be installed with:

cargo install cargo-expand

and then is run using:

cargo expand

Flamegraphs

Flamegraphs are helpful to analyse where the application is spending all of its time. The simple way to use this is to install it:

cargo install flamegraph

And then it can be run against binaries, tests, benchmarks. This is an example commandline for running it against the flakey-component binary with a few arguments.

CARGO_PROFILE_RELEASE_DEBUG=true sudo RUSTC_WRAPPER="" cargo flamegraph --bin flaky-component -- --num-packets 500000

Note: This must be run with as root when running on macOS.

Note: This is usually most useful against the release build.

Profiling

Developing on MacOS

The XCode Instruments profiling tools can be used via the cargo-instruments crate. To install it:

xcode-select --install
cargo install cargo-instruments

The list of templates describes the preconfigured set of probes avaliable which can be enabled during the profiling run. The current list of avaliable templates can be shown with:

cargo instruments --list-templates

For example to profile memory allocations in the flakey-component binary, running:

cargo instruments --template Allocations --time-limit 2000000 --bin flaky-component -- --num-packets 500000

will capture a trace file and open with the Instruments GUI.

Code Coverage

Generating Code Coverage

There is a recipe provided for generating code coverage for all the tests in the test suite:

cargo run -p gwr-terminus -- run --recipe gwr-code-coverage/recipes/coverage.yaml

If needed, the recipe will tell you what tools to install and how. The recipe also prints the location of the HTML coverage report it generates so that you can open it in a browser of your choosing.

diff-coverage

If you want to compare the coverage from two runs or worktrees then you can use the diff-coverage tool. This is a utility for showing the differences between coverage reports. This tool compares llvm-cov JSON output files.

Summary reports show just the overall summary and per-file summaries:

cargo run --bin diff-coverage -- [BEFORE_PATH]/summary.json [AFTER_PATH]/summary.json > diff.md

Full reports add details of how the line coverage has changed within each of the source files with annotated code listings:

cargo run --bin diff-coverage -- [BEFORE_PATH]/details.json [AFTER_PATH]/details.json > full_diff.md

Within the full reports the line coverage changes are shown with a context of unchanged lines. Use -C/--context to change the number of lines in the context.