Developer Guide

Setting up Rust

The easiest way to set up Rust toolchain is with https://rustup.rs/. By default, only stable toolchain is installed. Active Rust development also requires nightly toolchain:

rustup install nightly

Building and testing

Build is done with cargo tool, just like any other Rust project.

cargo build
# or
cargo build --release

Tests can also be done with cargo test command, but a much better way is to use nextest tool. To install it, do cargo install cargo-nextest. Then run tests with the following command:

cargo nextest r

nextest is much faster than the default test runner.

Running check tests

There are also check-tests, which are very similar to LLVM Integrated Tests. An easy and quick way to run those is to invoke cargo run --bin check-runner. However, a more convenient way for day-to-day use is cargo-make:

cargo install cargo-make
cargo make check # run build and check tests
cargo make check-only # only run check whithout re-building TIR
cargo make test # run build, cargo tests and check

Running fuzz tests

We also have fuzzing set up for each user input parser, like a disassembler or an IR parser. These tests also require an external tool, that can be installed with a command like cargo install cargo-fuzz. The usage is very simple:

# List tests
cargo fuzz list
# Run specific test
cargo +nightly fuzz run fuzz_riscv_disassembler -- -max_total_time=60 -max_len=16384

Collecting coverage info

WARNING!!! Coverage tool creates a lot of temp files in your working directory. You better commit all your changes to be able to use git to clean up.

Install dependencies:

rustup component add llvm-tools-preview
cargo install grcov

Run tests with special flags:

CARGO_INCREMENTAL=0 RUSTFLAGS='-Cinstrument-coverage' LLVM_PROFILE_FILE='cargo-test-%p-%m.profraw' cargo test
grcov . --binary-path target/debug/ -s . -t coveralls+ --branch --llvm \
    --ignore '../*' --ignore "/*" --ignore 'macros/*' --ignore 'fuzz/*' \
    --ignore '**/tests/**' -o target/coverage/html

Open target/coverage/html/index.html to see the report.

Also main branch reports are available at https://coveralls.io/github/perf-toolbox/tir.