rust-bench documentation

中文版：README_CN.md

This is the unified index for the rust-bench documentation set. It covers both reference docs (factual/structural — what things are) and guides (procedural — how to do things). The two layers cross-link: guides link to reference for background, reference links to guides for runbooks.

For the project overview and quick start, see the root README.md.

Reference docs

Factual/structural descriptions of the system.

• Glossary — domain terminology (runtime, testing, analysis, job queue, platforms/repos).
• Architecture — components (Site/Collector/Database/benchlib), multi-platform/multi-repo model, request lifecycle, data model.
• Configuration — site-config.toml field reference (keys, repos, collectors, per-collector benchmark overrides, env fallback).
• Job queue — distributed queue mechanics: request states, queue ordering, job enqueue, backfilling, retries.
• Deployment — deployment model (Docker image, Postgres, collect-job-queue.sh, env vars, machine preparation).
• Comparison analysis — significance (IQR fence), magnitude buckets, relevance; per-test-result only.
• Database schema — runtime + job-queue + artifact + error tables (compile-time tables out of scope).
• Manual modifications — exceptional DB operations (purge_artifact, re-queue, deactivate collector).

Guides

Step-by-step runbooks. Each has prerequisites → steps → verification → troubleshooting.

• Run benchmarks locally — bench_runtime_local, filters, output, bench_cmp TUI.
• Write a runtime benchmark — #[bench] macro and the custom benchmark framework.
• Profile a runtime benchmark — Cachegrind and perf-record; diffing two rustc builds.
• Deploy the Site — Docker/Postgres, site-config.toml, env vars, webhook endpoint.
• Deploy a Collector — registration, collect-job-queue.sh, machine prep, multi-architecture.
• Integrate GitCode and GitHub — webhook setup, /rust-bench commands, fork PRs, completion comments.

Scope note

This documentation set covers runtime benchmarks and the distributed benchmarking system. Compile-time benchmark machinery inherited from upstream rustc-perf exists in the codebase but is deliberately out of scope here.