Contributing
Development environment
The repository has a devenv setup with Rust, D-Bus,
pkg-config and mdBook:
devenv shell
Without devenv, install a Rust toolchain (1.85+), plus libdbus-1-dev and
pkg-config if you build the bluetooth feature.
Checks
cargo fmt --check
cargo clippy --all-features --all-targets -- -D warnings
cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps
The test suite contains:
| Suite | What |
|---|---|
| doctests | Every example in the API docs and in this book runs against the simulator |
tests/protocol.rs | Byte-exact encoding and decoding of every command |
tests/proptest.rs | Property tests: decoders never panic, value ranges |
tests/high_level.rs | The high-level API against the simulator |
tests/compile_fail.rs | Things that must not compile (tests/ui/*.rs) |
tests/tiers.rs | The high-level API uses only the public low-level API |
tests/hardware.rs | Real-brick tests, ignored by default |
When a compile-fail case’s error message changes, regenerate the expected output and review the diff:
TRYBUILD=overwrite cargo test --all-features --test compile_fail
Hardware tests need a brick on USB with nothing attached to output A:
NXT_TEST_USB=1 cargo test --all-features --test hardware -- --ignored --test-threads=1
This book
The book lives in docs/ and is built with mdBook
(included in the devenv shell). Pushes to master that touch docs/ publish
it to https://forge-pages.wvffle.net/wvffle/nxt-rs/
(.forgejo/workflows/book.yml).
mdbook serve docs # http://localhost:3000
mdbook build docs # into docs/book/
Every Rust code block is compiled and run as a doctest (see the book
module at the end of src/lib.rs). Lines starting with # are hidden in
the rendered book but still compiled. Use them for setup:
```rust
# nxt_rs::doc_example(|brick| async move {
let battery = brick.battery().await?;
# Ok(()) });
```
doc_example runs the closure against a simulated brick, and
doc_example_with also passes the Simulator. Use rust,no_run for code
that needs real hardware, and rust,compile_fail for code that must not
compile. When you add a page, add it to SUMMARY.md and to the pages!
list in src/lib.rs. A test checks that both stay in sync.
Design
PLAN.md describes the architecture and the reasoning behind it: the two
tiers, port claims, the sans-I/O protocol layer and the transports.