wip: bench wraps bench.sh

1 files changed, 15 insertions, 0 deletions

diff --git a/ONBOARD.md b/ONBOARD.md
index 35d5e35..7a7d46d 100644
--- a/ONBOARD.md
+++ b/ONBOARD.md
@@ -201,6 +201,21 @@ language server is interpreted and slow; `ZC_TEST_TIMEOUT_SCALE` stretches the
 drivers' deadlines (the suite sets it). `LLVM_CONFIG` selects an llvm with
 headers for the llvm section.
 
+### benchmarks
+
+`make bench` times the benchmark programs on `build/bin/zy` (the host's jit where
+there is one) and writes `build/bench.txt`: the kernels of `tests/programs/bench.zc`
+(collatz, sieve, digits, fib, each plain and o3) and the pointer sweep of
+`tests/bench/sweep.zc` (checked and unbounded). each figure is ms per repetition, the
+median of five slopes between one repetition and many, so start-up and compile time
+cancel out. the checks column waits for `--explain-checks` and the peak heap and gc
+mark columns for runtime counters that do not exist yet; they show `-`.
+`make bench-save` keeps the result as `tests/bench.baseline`, and `make bench-check`
+(or `make bench CHECK=1`) measures again and fails when a program is more than 10%
+slower, or keeps more checks once both sides have a count. a program that looks slower
+is measured up to twice more before it counts. the baseline belongs to the machine it
+was saved on: save a new one after changing machines, and expect noise on a busy host.
+
 ## 9. history and open work
 
 `docs/history/README.md` is the scrapbook of earlier stages and `TODO.md` the