# Rust Development Environment

## Pinned baseline

[rust-toolchain.toml](../rust-toolchain.toml) pins Rust **1.97.1**, the minimal
profile, and `rustfmt`/`clippy`. The native development host is
`x86_64-unknown-linux-gnu`; the additional `x86_64-unknown-linux-musl` target is
for executables running in Alpine integration containers. The host target is
implicitly included by rustup. Do not force all Cargo builds to musl.

Use Rust edition 2024 when creating Cargo.toml. Set its `rust-version` to
`1.97.1` as the initial supported compiler floor; this is distinct from the
exact toolchain pin. Do not claim compatibility with older compilers without
testing it. Keep Cargo.lock tracked once the package exists.

## Toolchain selection

With rustup-managed Cargo/rustc proxies, entering the repository selects the
toolchain file and may download missing components. Check `rustup show` and
`rustup target list --installed`; explicit overrides may take precedence.
Do not automatically install a global toolchain or modify the user's PATH.

This host currently uses system-packaged tools under `/usr/bin`, without
`rustup`. Such binaries do not enforce rust-toolchain.toml. Before execution,
verify the installed compiler and Cargo match the pin, and that formatter and
Clippy are available. If versions differ, stop the affected build and report
the mismatch rather than silently updating the pin.

Checks available before Cargo scaffolding:

```sh
rustc -Vv
cargo -V
rustfmt --version
cargo clippy --version
```

After scaffolding, use the completion commands in [AGENTS.md](../AGENTS.md).
The first dependency resolution generates Cargo.lock; subsequent checks use
`--locked`. Registry access or a populated cache is required for dependencies.

## Alpine target

The toolchain file requests the musl Rust standard library; it does not supply
all native compilers/linkers needed by a cross build. Establish the musl linker
and any C dependency requirements before milestone 8, or build in a dedicated
Alpine/musl builder. Keep build tools out of the small runtime test image.

Once prerequisites and Cargo scaffolding exist, the planned cross-build check is:

```sh
cargo build --locked --release --target x86_64-unknown-linux-musl
```

Then run the built executable in Alpine and inspect actual dynamic-library
requirements. A target name alone is not evidence that the binary runs there.
Musl readiness is a milestone 8 prerequisite, not a milestone 1 acceptance gate.

## Observed preparation state

During preparation, local commands reported:

- rustc: `1.97.1`, host `x86_64-unknown-linux-gnu`.
- Cargo: `1.97.1`.
- rustfmt: `1.9.0-stable`.
- Clippy: `0.1.97`.
- `rustup` and `musl-gcc`: not found in PATH.
- The musl standard library directory reported by rustc does not exist.

No toolchain, component, target, or native package installation was performed.
These observations establish tool availability, not a successful project build.
Recheck the environment at execution time.

Reference: [rustup toolchain files and overrides](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file).