Rust reference

Toolchains, channels, and components¶

rustup command surface. Toolchain selection precedes Cargo resolution: the selected Cargo and rustc versions can change accepted manifests, resolver behavior, diagnostics, and artifacts. Sources: The rustup book: Toolchains; The rustup book: Components; The rustup book: Cross-compilation.

# rust-toolchain.toml — pin what CI and local proxies select.
[toolchain]
channel = "1.98.0"
profile = "minimal"
components = ["clippy", "rustfmt"]
targets = ["wasm32-unknown-unknown"]

The stable channel is the deployment default for most projects. Beta tests the next release; nightly exposes unstable compiler and Cargo features and may occasionally lack optional components. Treat a nightly date as a dependency when it is required by a build.

Back to top

Project anatomy¶

The package-model vocabulary. In particular, package and crate are not synonyms. Source: The Cargo Book: Glossary; The Cargo Book: Workspaces.

workspace/
├── Cargo.toml          # [workspace], shared dependencies/lints/profiles
├── Cargo.lock          # concrete resolution for the workspace
├── rust-toolchain.toml # compiler/tool selection (rustup)
├── crates/
│   ├── domain/         # library package: stable application concepts
│   ├── adapters/       # library package: DB/network integrations
│   └── service/        # binary package: composition root
└── .cargo/config.toml  # target/linker/build environment policy

Keep dependency direction visible: domain packages should not need transport, database, or runtime adapters. The binary package is usually the composition root that selects implementations and operational policy. This is an architectural convention, not a rule Cargo infers.

Back to top

Manifest and workspace keys¶

High-impact stable Cargo.toml tables. Source: The Cargo Book: The Manifest Format; The Cargo Book: Workspaces; The Cargo Book: Lints.

[workspace]
members = ["crates/domain", "crates/adapters", "crates/service"]
resolver = "3"

[workspace.package]
edition = "2024"
rust-version = "1.85"
license = "MIT OR Apache-2.0"

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }

[workspace.lints.rust]
unsafe_code = "forbid"

[profile.release]
lto = "thin"
panic = "abort"

Workspace inheritance centralizes a constraint; it does not automatically make every dependency public to every member. A member still opts in with dependency.workspace = true. Profile sections are read from the workspace root. A virtual workspace has no root package edition from which to infer a resolver, so declare it explicitly.

Back to top

Dependencies, features, and resolution¶

Cargo dependency-resolution concepts. Sources: The Cargo Book: Dependency Resolution; The Cargo Book: Features; The Cargo Book: Workspaces.

[features]
default = ["tls-rustls"]
tls-rustls = ["dep:rustls"]
metrics = ["dep:metrics"]

[dependencies]
rustls = { version = "0.23", optional = true }
metrics = { version = "0.24", optional = true }

Features should be additive: enabling two callers’ feature sets must not silently select incompatible global modes. If two backends are mutually exclusive, prefer separate adapter crates, an explicit runtime constructor, or a build error that makes the illegal combination visible. Test default, no-default, all, and supported feature combinations rather than assuming one successful build covers the graph.

cargo tree --workspace --target all --all-features
cargo tree -e features
cargo tree -d                       # duplicate package versions
cargo metadata --format-version 1   # machine-readable resolved graph
cargo update -p package --precise 1.2.3

Back to top

Build, test, lint, and documentation commands¶

A layered local/CI gate. No one command establishes correctness, portability, soundness, or supply-chain trust. Sources: The Cargo Book: Commands; The Cargo Book: cargo test; The Cargo Book: cargo doc; Rust tools; Miri.

Integration tests under tests/ compile as separate crates and exercise only public API. Unit tests inside modules can reach private items. Documentation tests keep examples executable. Cross-target tests need a runner or deployment environment; compiling for another target is not the same as executing there.

Back to top

Profiles, artifacts, and reproducibility¶

Cargo profile controls with architecture impact. Defaults can evolve; inspect the linked reference for the selected toolchain. Source: The Cargo Book: Profiles; The Cargo Book: Build Cache.

--locked refuses lockfile changes. --offline refuses network access. --frozen requests both. They constrain Cargo’s inputs but do not by themselves make every build bit-for-bit reproducible: native toolchains, environment variables, paths, timestamps, build scripts, and linker behavior may still vary. Preserve the toolchain file, lockfile, target, native dependencies, and build environment as one release input.

The target directory contains final and intermediate artifacts, fingerprints, incremental caches, build- script outputs, generated docs, and package archives. With --target, host build scripts and proc macros are separated from target artifacts. Do not treat paths inside the internal build directory as a stable API; consume declared outputs and Cargo metadata instead.

Back to top

Targets, no_std, linking, and FFI¶

Deployment shapes and their explicit runtime boundary. Sources: rustc Platform Support; The rustup book: Cross-compilation; The Embedded Rust Book: no_std; The Rustonomicon: FFI; PyO3 user guide; CXX Rust/C++ interop; The wasm-bindgen Guide.

# Show target facts from the selected compiler.
rustc --print target-list
rustc --print cfg --target x86_64-unknown-linux-gnu

# Install Rust's target library, then provide the required linker/SDK separately.
rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown

#[repr(C)] requests a C-compatible representation for supported types; it does not make Rust strings, vectors, trait objects, enums with data, or panics into portable C APIs. Prefer opaque handles, fixed-width scalars, explicit byte spans, paired allocation/free functions, and status/error values. State which side owns every allocation and never unwind through a foreign ABI that does not permit it.

Back to top

Publication and compatibility¶

Cargo publication lifecycle. crates.io is designed as a permanent archive: yanking changes future resolution, not existing locked builds. Source: The Cargo Book: Publishing on crates.io; The Cargo Book: Registry Index.

Cargo’s SemVer guidance treats more changes as breaking than signature comparison alone suggests: removing public items, tightening generic bounds, adding trait requirements, changing feature behavior, or exposing new trait implementations can affect downstream type inference and coherence. Run downstream tests and inspect public API diffs, but keep the human compatibility contract explicit. The rust-version field declares the minimum supported Rust version; testing it remains the publisher’s responsibility. Source: The Cargo Book: SemVer Compatibility; The Cargo Book: The Manifest Format.

Back to top

Inspection and assurance workflow¶

Review layers for a Rust dependency graph. Each answers a different question; passing one is not evidence for the others. Sources: The Cargo Book: cargo metadata; The Cargo Book: Build Scripts; The Rustonomicon: Working with Unsafe; RustSec Advisory Database; cargo-deny documentation; cargo-vet documentation; Miri; Criterion.rs documentation.

# A compact release gate; add target- and project-specific jobs around it.
cargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --locked
cargo doc --workspace --no-deps
cargo tree -d

A deep review records exceptions: why a duplicate version remains, which native toolchain is trusted, which unsafe invariant was checked, which features are intentionally excluded, and which targets were compiled versus executed. The command transcript is evidence only when paired with the exact toolchain, lock graph, target, and configuration that produced it.

Back to top

Sources¶

Official Rust and Cargo documentation defines the toolchain. Project-owned documentation defines each optional ecosystem tool. Snapshot date: 2026-09-03.

1. The rustup book: Toolchains, The Rust Project.
2. The rustup book: Components, The Rust Project.
3. The rustup book: Cross-compilation, The Rust Project.
4. The Cargo Book: Glossary, The Rust Project.
5. The Cargo Book: The Manifest Format, The Rust Project.
6. The Cargo Book: Workspaces, The Rust Project.
7. The Cargo Book: Dependency Resolution, The Rust Project.
8. The Cargo Book: Features, The Rust Project.
9. The Cargo Book: Profiles, The Rust Project.
10. The Cargo Book: Build Cache, The Rust Project.
11. The Cargo Book: Commands, The Rust Project.
12. The Cargo Book: cargo test, The Rust Project.
13. The Cargo Book: cargo doc, The Rust Project.
14. The Cargo Book: Publishing on crates.io, The Rust Project.
15. The Cargo Book: Registry Index, The Rust Project.
16. The Cargo Book: SemVer Compatibility, The Rust Project.
17. The Cargo Book: Lints, The Rust Project.
18. The Cargo Book: cargo metadata, The Rust Project.
19. Rust tools, The Rust Project.
20. Miri, The Rust Project.
21. rustc Platform Support, The Rust Project.
22. The Embedded Rust Book: no_std, The Rust Project.
23. The Rustonomicon: FFI, The Rust Project.
24. The Rustonomicon: Working with Unsafe, The Rust Project.
25. PyO3 user guide, PyO3 project.
26. CXX Rust/C++ interop, CXX project.
27. The wasm-bindgen Guide, wasm-bindgen project.
28. RustSec Advisory Database, RustSec.
29. cargo-deny documentation, Embark Studios.
30. cargo-vet documentation, Mozilla.
31. Criterion.rs documentation, Criterion project.