Performance Watcher

Performance and Verification

Correctness checks and performance measurements are deliberately separate. Build first, run the cross-platform verifier, then benchmark identical Release builds when a change can affect speed, memory, or package size.

Correctness

python3 tests/verify_cli.py --binary build/linux/rayomd
python tests/verify_cli.py --binary build/windows/rayomd.exe
ctest --test-dir build/linux --output-on-failure

tests/verify_cli.py does not run timing loops. CI builds Linux and Windows and runs the same verifier. Performance sampling lives in a separate workflow so host noise cannot turn correctness checks red.

Maintained benchmark entry point

Use tools/benchmark.py; generated corpora and reports stay under ignored benchmark-output/.

python tools/benchmark.py run -- --binary build/windows/rayomd.exe --platform windows --suite watch --label local
python3 tools/benchmark.py run -- --binary build/linux/rayomd --platform linux-wsl --suite watch --label local
python tools/benchmark.py compare -- --rayomd build/windows/rayomd.exe --root benchmark-output/pandoc --runs 5
python tools/benchmark.py competitors -- --rayomd build/windows/rayomd.exe --root benchmark-output/competitors
python3 tools/benchmark.py release -- --from-version 1.1.0 --suite quick

Suites are quick, watch, and full. Keep worker counts identical in batch comparisons. Linux release claims should run on native/ext4 storage; label /mnt/* WSL results because filesystem overhead can dominate batching and recovery.

Regression gate

Use an explicit record rather than mutable history:

python tools/benchmark.py run -- \
  --binary build/after/rayomd.exe \
  --platform windows \
  --suite watch \
  --baseline-record benchmark-output/perf-watch/<before>/record.json \
  --fail-on-slower-pct 5

Compare executable and packaged byte size as well as timing. A small win on one document does not justify a clear regression in larger documents, batching, memory, or release size.

Concurrency and reversible PDFs

python scripts/concurrency_benchmark.py \
  --binary build/windows/rayomd.exe \
  --corpus <folder> \
  --output benchmark-output/concurrency

python tools/benchmark.py reversible -- \
  --binary build/windows/rayomd.exe \
  --platform windows \
  --suite full

The concurrency harness records p50/p95, failures, and peak RSS at explicit worker counts. The reversible suite covers ordinary and embedded exports, batch/stdin-batch/serve, inspection, recovery, hostile inputs, source-scale memory, and raw-versus-Flate interoperability.

Keep the default build light

Use clean Release builds and leave dependency-expanding experiments off unless broad measurements justify them:

cmake -S . -B build/light -DCMAKE_BUILD_TYPE=Release \
  -DRAYOMD_USE_CURL=OFF \
  -DRAYOMD_USE_SIMDUTF=OFF \
  -DRAYOMD_ENABLE_LTO=OFF \
  -DRAYOMD_ENABLE_PROFILING=OFF \
  -DRAYOMD_ENABLE_TSAN=OFF \
  -DRAYOMD_PGO=OFF
cmake --build build/light --config Release

For the smallest portable Linux artifact, disable zlib discovery when PNG alpha is not required. Keep URL images opt-in, leave source embedding off unless exact recovery is needed, and size image assets appropriately. Images can dominate conversion time, output size, and memory.

Profiling, LTO, PGO, TSAN, and simdutf remain experiments. The source checkout's docs/development/performance.md is authoritative for version-specific switches and release gates.