From 29cad923a5e2d7dc3207c8d456440f8c37bfd7b6 Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 2 Nov 2026 12:03:02 +0100 Subject: add documentation --- docs/development.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/development.md (limited to 'docs/development.md') diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..93726b1 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,52 @@ +# Development + +## The loop + +```sh +cargo check --features mycelium,libp2p,tor,dashboard # does it compile: seconds +cargo quick # every test but the simulations: seconds +cargo sim # the simulations (src/simtest/): under a minute +cargo test --features mycelium,libp2p,tor,dashboard # both +cargo benchmarks # the benchmarks, in release builds +``` + +`cargo quick`, `cargo sim` and `cargo benchmarks` are aliases ([`.cargo/config.toml`](../.cargo/config.toml)), +with every transport and the dashboard (`dashboard`, `GET /admin/dashboard`; +[`docs/dashboard.md`](dashboard.md)). Each transport is a feature, none of them default, and a build +needs at least one: a transport left out takes its tests and dependencies with it +(`--features libp2p` builds neither `reqwest` and the daemon supervision of Mycelium, +nor arti; among Mycelium's tests is a swarm simulated on its envelope). + +The simulations send the wire encoding alone, as libp2p and Tor do; a simulated net +can put messages into a transport's envelope instead (`SimNet::with_codec`), and every +message kind is round-tripped through each codec (`wire::samples`). + +The dev profile ([`Cargo.toml`](../Cargo.toml)) keeps the loop short: the crate gets line tables only +(backtraces still name files and lines), and the dependencies are built optimised and +without debug info. Automerge's work dominates the tests, so they run several times +faster; the binaries are a quarter of the size, so they link faster. The dependencies +build once (a few minutes, longer on few cores); after that, a change rebuilds in +seconds. To step through a dependency in a debugger, override it locally (`debug = +true` for that package). + +Measured on 2 cores, `--features libp2p,tor` (before Mycelium became a feature), after +touching one file, with Cargo's default dev profile and with this one: + +| | Default profile | This profile | +|---|---|---| +| `cargo check` | — | 3 s | +| test build | 8 s | 6 s | +| binary build | 13 s | 6 s | +| tests but the simulations | 6 s | 1.4 s | +| all tests | 40 s | 31–35 s | +| test binary | 550–670 MB | 100–155 MB | + +## The simulations + +The simulations ([`src/simtest/`](../src/simtest/)) run whole nodes on a simulated network +([`transport/sim.rs`](../src/transport/sim.rs)), in real time: tokio's clock isn't paused, because a node's +document work runs on the blocking pool, which a paused clock doesn't wait for. So they +take as long as the protocol's timeouts make them, however fast the machine, and on a +busy machine some fail now and then (a node's timer fires before the work it waits for +is done). One failing alone (`cargo sim `) and passing then is that, not a +regression; one failing again and again is a regression. -- cgit v1.3.1