Rust Core Toolchain

rust-core-toolchain

Mechanics of the Rust toolchain : rustup (toolchain installer/manager), cargo (build/package orchestrator), rustc (compiler), clippy (linter), rustfmt (formatter). This skill is the operational complement to [[rust-core-language-versions]] (which covers editions, channels-as-concept, MSRV-as-policy). For Cargo.toml mechanics see [[rust-impl-cargo-project]]. For edition-2024 language-level changes see [[rust-syntax-edition-2024]].

Quick Reference

Tool boundaries

ALWAYS invoke clippy and rustfmt via their cargo subcommands (cargo clippy, cargo fmt), not as standalone binaries.

Install in one line

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

This installs rustup, which then installs rustc, cargo, rustfmt, and clippy on the default stable channel. Source : https://www.rust-lang.org/tools/install.

Channel matrix

NEVER ship production code on nightly without an explicit, documented reason and a pinned nightly date.

Component matrix

Install : rustup component add <name>. Source : https://rust-lang.github.io/rustup/concepts/components.html.

Cargo subcommand cheat sheet

Source : https://doc.rust-lang.org/cargo/commands/index.html.

Clippy lint categories (the seven plus two)

The clippy::all group covers correctness + suspicious + style + complexity + perf. Pedantic / restriction / nursery / cargo are explicit opt-in. Source : https://rust-lang.github.io/rust-clippy/master/.

rust-toolchain.toml (per-project override)

ALWAYS commit a rust-toolchain.toml for any project where CI and contributor toolchain must match.

[toolchain]
channel = "1.85.0"
components = ["rustfmt", "clippy", "rust-analyzer"]
targets = ["wasm32-unknown-unknown"]
profile = "minimal"

When rustup enters a directory containing this file, it auto-installs and uses the pinned toolchain. Source : https://rust-lang.github.io/rustup/overrides.html.

Decision Trees

"Which cargo command should I run?"

Did I change Cargo.toml?
├── YES → `cargo update` (lockfile) or `cargo build` (also resolves)
└── NO  → Did I change source?
         ├── Type-error iteration  → `cargo check` (fastest)
         ├── Need to run it        → `cargo run`
         ├── Need to test it       → `cargo test`
         ├── About to commit       → `cargo fmt && cargo clippy -- -D warnings && cargo test`
         └── About to publish      → `cargo publish --dry-run` first

"Which channel do I install?"

Does the project need a `#![feature(...)]` gate?
├── YES → nightly. Pin via `channel = "nightly-YYYY-MM-DD"` in rust-toolchain.toml + DOCUMENT WHY.
└── NO  → Are you on the release-train one cycle ahead?
         ├── YES (testing pre-release) → beta
         └── NO  → ALWAYS stable.

"Which clippy categories do I enable?"

Project type?
├── Application binary → clippy::all + perf + suspicious (the default warn set)
├── Library            → clippy::all + clippy::pedantic, carefully `#[allow]` noise
└── Embedded / unsafe-heavy → above + selected `clippy::restriction` lints (e.g. `clippy::unwrap_used`)

NEVER enable clippy::restriction as a group; always pick individual lints. Restriction lints contradict each other by design.

"Where do I configure lints?"

Configure-once across crate?
├── Cargo.toml [lints.clippy] (since 1.74)  → preferred
├── Cargo.toml [lints.rust]                 → rustc warnings
└── crate-root attribute `#![warn(clippy::pedantic)]` → also valid, but less discoverable

Per-line allow?
└── `#[allow(clippy::lint_name)]` directly above the item.

Source : https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section.

"Which rustc optimization level?"

Profile?
├── dev (default for `cargo build`)              → opt-level = 0, full debug info
├── release (default for `cargo build --release`)→ opt-level = 3, line-tables-only
├── Size-constrained binary                       → opt-level = "z" (smallest) or "s" (small)
└── Production with reasonable size + speed       → opt-level = 3, LTO = "thin"

Profile defaults : https://doc.rust-lang.org/cargo/reference/profiles.html.

Patterns

Pattern : pin a toolchain in CI and locally

ALWAYS commit rust-toolchain.toml so rustup resolves the same toolchain in CI and on developer machines.

# rust-toolchain.toml
[toolchain]
channel = "1.85.0"
components = ["rustfmt", "clippy", "rust-analyzer"]
profile = "minimal"

When CI runs cargo check, rustup first installs 1.85.0 with the listed components, then dispatches to it. NEVER rely on the host's default toolchain in CI.

Pattern : cross-compile to a new target

rustup target add aarch64-apple-darwin
cargo build --release --target aarch64-apple-darwin

For non-trivial targets (Windows-from-Linux, bare-metal), a target-specific linker plus .cargo/config.toml is required. See [[rust-impl-cargo-project]] for cross-compile workflows.

Pattern : project-level lint configuration

In Cargo.toml (Rust 1.74+) :

[lints.rust]
unsafe_code = "forbid"

[lints.clippy]
pedantic = { level = "warn", priority = -1 }
unwrap_used = "deny"
expect_used = "deny"

The priority field lets group-level lints (pedantic) be overridden by specific lints. Source : https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section.

Pattern : rustfmt configuration

# rustfmt.toml
edition = "2024"
max_width = 100
use_field_init_shorthand = true
imports_granularity = "Crate"  # nightly-only option as of 1.85

ALWAYS set edition in rustfmt.toml explicitly. Stable rustfmt ignores unstable options without error unless invoked with +nightly. Source : https://rust-lang.github.io/rustfmt/.

Pattern : MSRV declaration

Declare the Minimum Supported Rust Version in Cargo.toml :

[package]
name = "my-crate"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"

cargo build refuses to compile with a rustc older than rust-version. Since Rust 1.84, the MSRV-aware resolver (opt-in via resolver.incompatible-rust-versions = "fallback" in .cargo/config.toml) selects dep versions compatible with your MSRV. Source : https://blog.rust-lang.org/2025/01/09/Rust-1.84.0/.

Pattern : enforce clippy in CI

cargo clippy --all-targets --all-features -- -D warnings

-D warnings promotes every warning (including warn-by-default clippy categories) to a hard error. ALWAYS run this in CI for libraries.

Reference Links

• references/methods.md : Full surface of rustup, cargo, rustc, clippy lint categories, rustfmt options.
• references/examples.md : End-to-end snippets for install, channel switch, cross-compile, lint config, MSRV setup, rust-toolchain.toml.
• references/anti-patterns.md : Common toolchain mistakes with WHY-this-fails explanations.

Cross-References

• [[rust-core-language-versions]] : Channels-as-concept, editions, MSRV-as-policy, version matrix.
• [[rust-syntax-edition-2024]] : Language-level edition 2024 changes consumed via the toolchain.
• [[rust-impl-cargo-project]] : Cargo.toml manifest details, workspaces, features, [lints] table, profiles.
• [[rust-impl-testing]] : Test runners, cargo test, cargo bench.

Source Verification

All claims verified against :

• https://rust-lang.github.io/rustup/concepts/toolchains.html (rustup model)
• https://rust-lang.github.io/rustup/concepts/components.html (components)
• https://rust-lang.github.io/rustup/overrides.html (rust-toolchain.toml)
• https://doc.rust-lang.org/cargo/commands/index.html (cargo subcommands)
• https://doc.rust-lang.org/cargo/reference/profiles.html (profiles + opt-level)
• https://doc.rust-lang.org/cargo/reference/manifest.html ([lints], rust-version)
• https://rust-lang.github.io/rust-clippy/master/ (lint categories)
• https://rust-lang.github.io/rustfmt/ (rustfmt options)
• https://blog.rust-lang.org/2025/01/09/Rust-1.84.0/ (MSRV-aware resolver)
• https://blog.rust-lang.org/2025/02/20/Rust-1.85.0/ (Edition 2024 stable, cargo new defaults)

Last verified : 2026-05-19.