From ce4a1a127dd25b296afc32b592f240c93a2900a5 Mon Sep 17 00:00:00 2001 From: Tyler Hallada Date: Fri, 7 Aug 2026 00:35:12 +0000 Subject: [PATCH] docs(build): quantify the double-compile cost instead of guessing The previous text claimed restructuring main.rs to use the lib crate would 'roughly halve' build time. Measured with --timings on a clean release build, that was wrong: 33.7s keydr (bin) 26.0s keydr (lib) 1.4s generate_test_profiles (bin) 61.0s of 292.2s total unit-seconds (21%) The duplicated units are indeed the two slowest in the graph, but the saving is ~26s of unit-work (less in wall time, since they overlap with dependency compilation across 3 jobs), not half the build. The other ~79% is one-time dependency compilation that incremental builds skip. Replace the estimate with the measurement. --- docs/BUILDING.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/BUILDING.md b/docs/BUILDING.md index 177de49..c938a1a 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -95,9 +95,27 @@ compiles twice** — once for the lib, once for the bin. The `i18n!` macro must therefore be invoked in both crate roots (`t!()` expands to `crate::_rust_i18n_t`, so it must exist in each crate). -With v4 this duplication is cheap (21 calls, not 8,652), so it's no -longer worth fixing for build performance alone. If you ever restructure -`main.rs` to `use keydr::...`, build time would roughly halve again. +Measured with `cargo build --release --timings` on a clean tree, the two +duplicated units are the slowest in the whole graph: + +``` + 33.7s keydr (bin) + 26.0s keydr (lib) + 1.4s generate_test_profiles (bin) + ------ + 61.0s of 292.2s total unit-seconds (21%) +``` + +So restructuring `main.rs` to `use keydr::...` would save roughly 26s of +compile work — real, but nowhere near half the build. Wall-clock saving is +smaller still, since those units partly overlap with dependency +compilation across 3 parallel jobs (292s of unit-work compressed into +~2m15s wall). Worth doing for code hygiene; not a build-performance +emergency. + +Note the remaining ~79% is dependency compilation (`reqwest` 12.7s, +`clap_builder` 11.4s, `toml_edit` 9.3s, `tokio` 8.0s...), which is +one-time work that incremental builds skip entirely. ---