Cargo Highlights Summary

Every highlight bullet from the 11 pages in this section, gathered on one page and grouped by the page it came from.

How Cargo Thinks About Dependencies and Builds

• Cargo.toml states intent (version ranges); Cargo.lock records fact (exact versions actually built).
• Cargo resolves one dependency graph per workspace, not one per crate that uses it.
• Feature unification means enabling a feature anywhere in the graph enables it everywhere that dependency is used.
• A workspace shares one Cargo.lock and one target/ directory across every member crate.
• cargo check, build, and test all start from the same resolved graph; only the compilation step differs.

Cargo Basics

• Rust 1.97.0 and edition 2024 are prerequisites for Cargo
• cargo new scaffolds a runnable project with Cargo.toml and src/main.rs
• Use cargo new --lib to create a reusable library crate
• cargo build compiles your code; cargo run compiles and executes
• cargo test runs unit, integration, and documentation tests
• Declare dependencies in Cargo.toml or use cargo add

Cargo.toml Explained

• Cargo.toml declares crate identity, dependencies, features, and profiles
• Use Cargo.toml to add crates, pin Rust versions, or tune build profiles
• The edition field selects language defaults for the crate
• rust-version tells Cargo the Minimum Supported Rust Version (MSRV)
• Feature flags on dependencies trim unused code paths from builds
• [profile.release] tunes the shipping binary for optimized performance

Features & Optional Dependencies

• Cargo features enable optional code paths and dependencies
• Use dep: syntax to tie a feature directly to an optional crate
• Test your library with --no-default-features and --all-features
• Features can enable other features with union semantics
• Features are compile-time only, not runtime toggles

Profiles & Build Settings

• Cargo profiles control optimization, debug info, panic strategy, and LTO
• opt-level = 3 maximizes runtime performance in release builds
• codegen-units = 1 improves optimization at the cost of compile time
• panic = "abort" reduces binary size but requires careful testing
• Benchmark with --release always, as debug builds differ significantly
• Use thin LTO in CI to avoid link step timeouts

Workspaces

• A Cargo workspace builds multiple crates with one shared Cargo.lock
• Use [workspace] in Cargo.toml to define members and shared dependencies
• Path dependencies connect internal crates without publishing
• cargo test --workspace --all-targets tests all members in CI
• Avoid circular path dependencies by extracting shared types to a core crate
• cargo publish on a member requires replacing path dependencies with versioned ones

Build Scripts (build.rs)

• Cargo runs build.rs before compiling your crate
• Build scripts generate code, link libraries, and emit cfg flags
• Use cargo:rerun-if-changed to prevent stale builds
• Generated code goes into OUT_DIR and is included via include!
• Build script failures block compilation with clear errors

Dependency Management

• Pin reproducible dependency graphs, update deliberately within semver, and audit for vulnerabilities
• Use cargo update to refresh Cargo.lock, not Cargo.toml version requirements
• Use cargo tree -i to find reverse dependencies for a specific crate
• Run cargo audit weekly to match your lockfile against the RustSec advisory database
• Implement cargo deny check to enforce license and dependency policies in CI
• Commit lockfile changes with passing tests to prevent broken builds on fresh clones

Useful Cargo Subcommands

• Use cargo expand to debug macro-generated code
• Use cargo tree to visualize and deduplicate dependencies
• Use cargo bloat to analyze binary size by symbols and crates
• Use cargo nextest for faster, parallel test execution
• Use cargo watch to rerun commands on file changes
• Install tools like cargo-expand with cargo install

Publishing to crates.io

• Publishing makes a crate available to the ecosystem via cargo add
• Use cargo publish --dry-run to catch packaging mistakes before upload
• Include legal and discovery metadata like license and description
• Follow SemVer; treat minor versions as breaking for pre-1.0 crates
• Yank prevents new resolves; deletion of published versions is not supported
• Avoid publishing path dependencies; publish dependencies first

Cargo Best Practices

• Commit Cargo.lock for applications
• Workspace-shared dependency versions
• CI runs fmt, clippy, and test --workspace
• Features stay minimal and documented