add documentation

1 files changed, 52 insertions, 0 deletions

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 <name>`) and passing then is that, not a
+regression; one failing again and again is a regression.