wireguard-admin/docs/ENVIRONMENT.md

Rust Development Environment

Pinned baseline

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:

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

After scaffolding, use the completion commands in 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:

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.