How to Work on Fidius
This guide covers the development tools and workflows for contributing to fidius.
Prerequisites
Section titled “Prerequisites”- Rust toolchain (stable)
- angreal — task runner
- pre-commit — git hook manager
Working on the WASM execution backend additionally needs the component build toolchain — see How to Set Up the WASM Component Toolchain. Not required for the cdylib or Python backends.
Install Pre-commit Hooks
Section titled “Install Pre-commit Hooks”pre-commit installThis enables three hooks that run on every commit:
- license-header — checks all
.rsfiles have the Apache 2.0 copyright header - rustfmt — checks code formatting
- clippy — runs clippy with
-D warnings
Angreal Tasks
Section titled “Angreal Tasks”| Command | Purpose |
|---|---|
angreal build |
cargo build --workspace |
angreal build --release |
Release build |
angreal test |
cargo test --workspace |
angreal test --release |
cargo test --workspace --release |
angreal check |
cargo check --workspace + cargo clippy --workspace |
angreal lint |
cargo fmt --all --check + clippy |
angreal coverage |
Test coverage (per-crate summary + HTML + lcov) via cargo-llvm-cov |
angreal license-header |
Add Apache 2.0 headers to all .rs files |
angreal license-header --check |
Check headers without modifying files |
The wire format is bincode in both debug and release builds (0.1.0+).
There’s no longer a profile-specific wire path to regression-test, so
angreal test alone is sufficient for CI; --release is only useful when
you want optimized builds in the loop.
Measuring Test Coverage
Section titled “Measuring Test Coverage”Coverage is measured with cargo-llvm-cov
(source-based LLVM instrumentation). Install it once:
cargo install cargo-llvm-covrustup component add llvm-tools-previewThen run:
angreal coverage # workspace defaults + streaming (native surface)angreal coverage --open # also open the HTML report in a browserangreal coverage --wasm # best-effort: also instrument the wasm feature (see note)This prints a per-crate summary table and writes two artifacts under
target/coverage/ (git-ignored):
target/coverage/html/index.html— browsable HTML reporttarget/coverage/lcov.info— lcov for editors/CI tooling
The default surface is the workspace defaults plus streaming; python is left
off to match angreal test.
The
wasmfeature is not instrumented by default. Its tests buildwasm32-wasip2component fixtures at test time, and those sub-builds inherit cargo-llvm-cov’s-C instrument-coverageflags — which the wasm target rejects (instrument-coverage isn’t supported there), so the run fails. The wasm path’s correctness is covered by the non-instrumentedwasmCI job andangreal test; instrumenting it cleanly is a follow-on (it would need the fixture sub-builds to drop the coverageRUSTFLAGS).--wasmattempts it anyway, best-effort.
Report-only. Coverage is a map of what the tests exercise, not a gate —
angreal coveragenever fails on a threshold. The same measurement runs in CI (report-only, native surface, published to the job summary). See initiative FIDIUS-I-0033.
Fuzzing
Section titled “Fuzzing”Fidius fuzzes its untrusted-input boundaries with
cargo-fuzz (libFuzzer). The harness is
a standalone, nightly-only crate at crates/fidius-host/fuzz/ (detached from the
main workspace), with these targets:
| Target | Surface |
|---|---|
wire_value |
bincode Value decode + decode→encode→decode round-trip |
frame_read |
framed streaming-wire decode (length-prefix bounds) + round-trip |
manifest_validate |
PackageManifest parse + validate_runtime |
fid_extract |
.fid (tar+bzip2) safe extraction — unpack_fid |
Install and run locally (needs a nightly toolchain):
cargo install cargo-fuzzcd crates/fidius-host
cargo fuzz list # show targetscargo fuzz run wire_value # fuzz until you Ctrl-C (a long campaign)cargo fuzz run fid_extract -- -max_total_time=60 # time-boxed (CI does this)Committed seed corpora live under crates/fidius-host/fuzz/corpus/<target>/
and seed every run. Build artifacts and any crash findings (fuzz/target/,
fuzz/artifacts/) are git-ignored.
- Nightly CI fuzz (
fuzzjob in.github/workflows/nightly.yml): runs each target for 120s on a nightly schedule + release (v*) tags +workflow_dispatch— not per-PR (fuzz is too expensive for the fast gate). Report-only: a crasher is surfaced in the job summary + uploaded as an artifact but does not gate (FIDIUS-I-0033 posture; flip by removingcontinue-on-error). - Longer campaigns: run a target with no time limit locally, or on a schedule.
Minimize a grown corpus before committing with
cargo fuzz cmin <target>. Reproduce a CI crasher withcargo fuzz run <target> fuzz/artifacts/<target>/<crash-file>.
The Test Plugin
Section titled “The Test Plugin”The tests/test-plugin-smoke/ directory contains a Calculator plugin used by integration tests. It is excluded from the workspace (Cargo.toml exclude field) and built by tests via cargo build --manifest-path.
To build it manually:
cd tests/test-plugin-smoke && cargo buildRegenerating API Docs
Section titled “Regenerating API Docs”API reference docs are generated by plissken 0.2.1 from doc comments in source code:
angreal docs apiThis writes to docs/src/content/docs/reference/api/. The pages are not in git: the docs workflow renders them in CI, and angreal docs build and angreal docs serve render them first. Install plissken 0.2.1 from its release or with cargo install plissken --version 0.2.1 --locked.
Building the Docs Site
Section titled “Building the Docs Site”The docs are an Astro Starlight site in docs/. They need Node 22 or later.
angreal docs build # build into docs/distangreal docs serve # serve with live reloadProject Layout
Section titled “Project Layout”fidius-core/ Shared types (both host and plugin depend on this)fidius-macro/ Proc macros (#[plugin_interface], #[plugin_impl])fidius-host/ Host-side loading, validation, callingfidius-cli/ CLI binary (fidius)fidius-test/ Testing helpers (dylib_fixture, signing fixtures)fidius/ Facade crate re-exporting core + macrotests/ Test fixtures (test-plugin-smoke)docs/ Documentation site (tutorials, how-to, reference, explanation, api).angreal/ Angreal task definitions