Template Manual

This guide walks you through common development tasks—from getting started to advanced optimization—with links to detailed documentation as needed.

Prerequisites

Install Rust

choco install rust  # Chocolatey
scoop install rustup  # Scoop

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Code Editor Setup

VSCode

Install these recommended extensions:

• rust-analyzer - Rust language server for IDE features
• Coverage Gutters - Visualize code coverage in your editor
• Crates - Manage crate dependencies and versions

VSCode will prompt you to install these when you open the project, or install manually via the Extensions panel (Ctrl+Shift+X).

What are you editing?

Choose what you want to work on:

• Editing Code - Build, run, test, optimize, and create bindings
• Editing Documentation - Write and preview docs

Editing Code

Open the src folder in your code editor for source development.

For CLI users: All commands below assume you're in the src directory.

How to Build

Using VSCode:

Press Ctrl+Shift+B to open the build task menu. Select rust: cargo build.

From Command Line:

cd src
cargo build  # for debug builds
cargo build --release  # for optimized release builds

How to Run

Using VSCode:

While in a Rust file, press F5 or click the "Run and Debug" button to execute your project with debugging enabled.

From Command Line:

cd src
cargo run  # run debug build
cargo run --release  # run optimized release build

How to Debug

If using VSCode:

Install the CodeLLDB extension for native debugging support. Debug profiles are automatically created when the extension is installed.

How to Test

Using VSCode:

Access pre-configured testing tasks via Ctrl+Shift+P → "Run Task":

• Auto Test on Save - Automatically run tests when files change

From Command Line:

cd src
cargo test  # run all tests

When you push code, GitHub Actions automatically runs tests on Linux, Windows, and macOS—check the "Actions" tab to see results.

How to Lint

Using VSCode:

Linting runs automatically in VSCode with the rust-analyzer extension. You'll see warnings and suggestions directly in your editor as you type.

From Command Line:

cd src
cargo clippy  # run linter checks

Clippy will show warnings and suggestions to improve your code quality.

How to Check Coverage

Using VSCode:

Access pre-configured coverage tasks via Ctrl+Shift+P → "Run Task":

• Auto Coverage on Save - Automatically generate coverage reports when files change

You can preview coverage in the IDE directly with 'Coverage Gutters':

• Coverage Gutters: Preview Coverage Report - View HTML coverage report in browser

• Coverage Gutters: Watch - Live coverage visualization in editor (shows green/red lines)

When you push code, use the Codecov dashboard (click the coverage badge in your README) to track coverage trends and find untested code:

How to Check for Unsafe Code Issues and Undefined Behaviour

Using VSCode:

Press Ctrl+Shift+P → "Run Task" → Select Run Tests to Detect Undefined Behaviour to run Miri tests.

From Command Line:

First install Miri (one-time setup):

rustup +nightly component add miri

Run Miri tests in your project:

cd src
cargo +nightly miri test

# Run a single test
cargo +nightly miri test test_name

How to Benchmark

Run benchmarks:

cd src
cargo bench  # run all benchmarks

This generates detailed HTML reports in target/criterion/report/index.html.

Add benchmarks:

Create benchmark modules in benches/ directory. Example structure:

benches/
├── main.rs          # Entry point
└── my_bench.rs      # Your benchmarks

In main.rs:

mod my_bench;
use criterion::{criterion_group, criterion_main, Criterion};
use my_bench::bench_my_function;

fn criterion_benchmark(c: &mut Criterion) {
    bench_my_function(c);
}

criterion_group!(benches, criterion_benchmark);
criterion_main!(benches);

In my_bench.rs:

use criterion::Criterion;

pub fn bench_my_function(c: &mut Criterion) {
    c.bench_function("my_function", |b| {
        b.iter(|| {
            // Code to benchmark here
        })
    });
}

How to Profile

Install cargo-flamegraph globally (one-time setup):

cargo install cargo-flamegraph
# if on Linux, ensure `perf` and `objdump` are available/installed

Generate flamegraph:

cd src
cargo flamegraph --bench my_benchmark --profile profile -- --bench

cd src
# Requires administrator privileges - run in admin command prompt or with sudo
sudo cargo flamegraph --bench my_benchmark --profile profile -- --bench

Open the generated flamegraph.svg in your web browser to explore the interactive visualization.

Platform-specific tools:

perf report perf.data

cd src
cargo bench

How to Use Profile Guided Optimization (PGO)

Install cargo-pgo globally (one-time setup):

cargo install cargo-pgo
rustup component add llvm-tools-preview

Use in your project:

cd src
cargo pgo instrument test  # collect profiling data
cargo bench  # establish baseline
cargo pgo optimize bench  # build with PGO and compare

How to Build for Other Platforms

Install globally (one-time setup):

cargo install cross --git https://github.com/cross-rs/cross

Use in your project:

cd src
cross build --target x86_64-pc-windows-gnu  # build for Windows
cross test --target aarch64-unknown-linux-gnu --release  # test for ARM64 Linux

The cross tool uses Docker or Podman containers to handle cross-compilation automatically. Simply replace cargo with cross and specify your target platform.

How to Create C/C++ Bindings

Export functions:

Use #[no_mangle] and extern "C" to make functions callable from C/C++:

#[no_mangle]
pub extern "C" fn add_numbers(a: i32, b: i32) -> i32 {
    a + b
}

Generate bindings:

Using VSCode, press Ctrl+Shift+P → "Run Task" → Select one of:

• Generate C Bindings - Generate C headers only
• Generate C++ Bindings - Generate C++ headers only

Or from command line:

cd src

# Install cbindgen (one-time setup)
cargo install cbindgen

# Generate C bindings
cbindgen --config ../.github/cbindgen_c.toml --output bindings/c/your-project.h your-project

# Generate C++ bindings
cbindgen --config ../.github/cbindgen_cpp.toml --output bindings/cpp/your-project.hpp your-project

Replace your-project with your actual project name. Configuration files are located in .github/:

• .github/cbindgen_c.toml - C bindings configuration
• .github/cbindgen_cpp.toml - C++ bindings configuration

How to Create C# Bindings

Export functions:

Bindings are generated when you build into bindings/csharp/NativeMethods.g.cs. Customize generation in build.rs using csbindgen.

Editing Documentation

If using VSCode:

Open the doc/ folder in a new VSCode window (File → Open Folder) for formatting rules to apply.

Open a terminal and run:

python3 start_docs.py

Ctrl+click the http://localhost:8000 link in the terminal output to open the docs in your browser.

From Command Line:

To preview documentation locally:

cd doc
python3 start_docs.py

This starts a local server at http://localhost:8000 with live reload.

See doc/README.md for more information.

Contributing

One Change Per PR

Keep pull requests focused and atomic. Try to do one logical change per pull request rather than bundling multiple unrelated changes together.

Commit Names

When writing commit messages, follow the Keep a Changelog style to help maintain clear project history:

• Added - for new features
• Changed - for changes in existing functionality
• Deprecated - for soon-to-be removed features
• Removed - for now removed features
• Fixed - for any bug fixes
• Security - in case of vulnerabilities

Example commit messages:

Added support for async operations
Fixed memory leak in parser
Changed API parameter order (breaking change)

Miscellaneous

GitHub Workflows

The .github folder contains pre-configured issue templates, PR templates, and CI/CD workflows.

You may want to edit these to match your project's needs:

• Issue templates - Located in .github/ISSUE_TEMPLATE/
• Workflow files - Located in .github/workflows/

When you push code, these workflows automatically run tests on Linux, Windows, and macOS.