# Local Dev Setup
A short guide for getting Tokitai to build, test, and regenerate
paper artifacts on your own machine. If you only want to run a
single test, jump to **"Run a single test"** below.
## Prerequisites
- Rust toolchain at the version pinned by `rust-toolchain.toml`
(or your default stable if none is pinned). Install via
[rustup](https://rustup.rs/).
- A C/C++ toolchain for the `cc` crate (build-essential on
Debian/Ubuntu, Xcode CLT on macOS, or `gcc` + `make` on most
Linux distros).
- No GPU is required for the default build. ROCm/HIP modules are
gated behind `--features rocm-hip` and need a working ROCm
install; that path is documented separately under
`docs/rocm_hip_*`.
- `git` and `bash` (the CI uses GitHub Actions on `ubuntu-latest`).
## First Build
The first `cargo build` populates the offline cache, so it can use
the network. After that, `--offline` is the default.
```bash
# Online first time, offline thereafter.
cargo build
cargo build --offline
```
The release-mode build (`cargo build --release`) takes
significantly longer; the debug build is fast enough for iteration.
## Run All Tests
The full test sweep covers default features only. ROCm/HIP tests
are gated.
```bash
# Fast: skip ROCm/HIP, which need hardware.
cargo test --offline
# Equivalent to running every *.rs file under tests/ individually.
```
The 4 pre-existing `paper_artifacts.rs` content checks are
expected to fail on a fresh checkout (they assert the
`target/paper-results/` artifacts are present and current). The
fix is to regenerate them — see below.
## Run a Single Test
There are three useful granularities:
```bash
# 1. One test FILE (e.g. tests/shape_ops.rs).
cargo test --offline --test shape_ops
# 2. One TEST FUNCTION inside a file (e.g. reshape_ok_2x3_to_3x2).
cargo test --offline --test shape_ops reshape_ok_2x3_to_3x2
# 3. All tests in a module or with a name prefix.
cargo test --offline --test nn_ops relu_
```
For doctest runs:
```bash
cargo test --offline --doc
```
## Regenerate Paper Artifacts
Paper artifacts are produced by `examples/paper_benchmarks.rs` and
the helper scripts under `scripts/`. They land in
`target/paper-results/`:
```bash
# Main entry: regenerates every artifact the paper cites.
cargo run --offline --example paper_benchmarks
# Underlying helper, if you want to call it directly.
bash scripts/regenerate_paper_artifacts.sh
```
The artifact directory is git-ignored; never hand-edit
`target/paper-results/*`.
## Sanity Checks Before Pushing
```bash
cargo fmt --check # formatting gate (CI runs this)
cargo test --offline # full test sweep
cargo build --offline # full build under default features
```
Optionally, the release-gate and health checks (these are slower
but are the same checks CI runs):
```bash
cargo test --offline --test theory_release_gate
TOKITAI_HEALTH_SKIP_BUILD=1 bash scripts/health_check.sh
```
## Common Footguns
- **"no matching package"** when running `--offline` for the
first time — run `cargo build` once online to populate the
cache, then `--offline` works.
- **"permission denied"** on `target/` after switching branches
— `cargo clean && cargo build` resolves it.
- **ROCm/HIP tests failing under default features** — they are
expected to be absent; run them only with
`--features rocm-hip` on a ROCm-capable machine.
## Where to Read Next
- [`ARCHITECTURE.md`](../../ARCHITECTURE.md) — the 8-layer
architecture overview.
- [`ARTIFACT.md`](../../ARTIFACT.md) — what the paper claims and
which tests gate which claim.
- [`tests/README.md`](../../tests/README.md) — index of all
integration test files.
- [`scripts/README.md`](../../scripts/README.md) — index of all
helper shell scripts.
- `docs/development/ci_debugging.md` — how to read a failed CI
run.