The compiler loop

You build understanding of a codebase by changing it and seeing what happens. In Rust, the compiler is the first thing that happens — and it is unusually helpful. This lesson is the tight inner loop you’ll run hundreds of times.

You’ll be able to: get a compile signal in seconds, run exactly the tests you care about, keep formatting and lints clean, and — most importantly — read a Rust diagnostic and act on it.

The compiler is your first reviewer

Rust’s compiler doesn’t just say “no”; it explains what’s wrong and usually how to fix it. Run this, then break it on purpose:

rust // editable

fn main() {
  let tiers = ["gold", "standard"];
  for t in &tiers {
      println!("tier: {t}");
  }
}

fn main() {
  let tiers = ["gold", "standard"];
  for t in &tiers {
      println!("tier: {t}");
  }
}

> output appears here — press Run

It compiles and prints two lines. Now change {t} to {tee} and Run again. You won’t get a vague crash — you’ll get something like:

error[E0425]: cannot find value `tee` in this scope
 --> src/main.rs:4:30
  |
4 |         println!("tier: {tee}");
  |                          ^^^ help: a local variable with a similar name exists: `t`

A precise location, an error code you can look up, and a suggested fix. Reading these well is the single highest-leverage skill for working in a Rust codebase.

The inner loop: check → test → fmt → clippy

Clinker’s own command guide documents the gates; reach for the smallest one that covers your change and broaden as you go.

clinker ·50_TESTING_AND_COMMANDS.md doc @47d2e12

cargo check — fastest signal. It type-checks without generating a binary, so it’s much quicker than a full build. This is your every-few-seconds command:

cargo check -p clinker-record        # check one crate
cargo check --workspace              # check everything

cargo test — prove behavior. Run the tests at the boundary you touched, not the whole suite:

cargo test -p clinker-record                 # one crate's tests
cargo test -p clinker-exec value -- --exact  # a targeted test by name

cargo fmt --all --check — formatting. Reports formatting drift (drop --check to fix it).

cargo clippy — lints. Clinker runs clippy twice, and the order matters:

cargo clippy --workspace -- -D warnings
cargo clippy --workspace --all-targets -- -D warnings

The first pass deliberately omits --all-targets. Why? So that code which is only referenced from tests still trips the dead-code lint. It’s a small trick that keeps unused production code from hiding behind the test suite — and a good first taste of how seriously this project treats its lints (-D warnings makes every warning an error).

Clinker’s own diagnostics

The Rust compiler checks your code; Clinker checks your pipelines, and it has its own diagnostic codes. When a run fails with something like E105, ask the engine to explain it:

cargo run -p clinker -- explain --code E105

And the run itself reports outcome through its exit code — 0 clean, and distinct non-zero codes for a config/schema error, records sent to the DLQ, a CXL evaluation failure, or an I/O error. A script calling Clinker can branch on those.

Try it

✓ Lab

In the Playground above, introduce an error and read the compiler’s output before fixing it.

You should be able to:

`cargo check -p clinker-record` returns clean
A targeted `cargo test -p <crate>` passes
`cargo clippy --workspace -- -D warnings` is clean
You broke a snippet, read the diagnostic, and fixed it

Verify in the checkout:

cargo check -p clinker-record
cargo test -p clinker-record --lib -- --exact value::tests::test_value_enum_size
cargo fmt --all --check
cargo clippy --workspace -- -D warnings

💡 Hint 1

A quick way to provoke a clear diagnostic: use a value after moving it, or reference a name that doesn’t exist (like the {tee} typo above). The compiler will name the problem and often point at the fix.

What a good loop looks like

Edit → cargo check -p <crate> (seconds) → repeat until it compiles → cargo test -p <crate> <name> for the behavior you changed → cargo fmt --all and cargo clippy --workspace -- -D warnings before you call it done. Run the full workspace gates only when your change crosses crate boundaries.

// quick check

Why does Clinker run `cargo clippy` once *without* `--all-targets` before the full pass?

Without --all-targets, clippy sees only the library/binary targets — so a pub(crate) item referenced solely from tests shows up as dead code instead of being kept alive by the test that uses it.

You now have a feedback loop measured in seconds. Next: how to find your way around the thirteen crates that make up the engine.