Cargo & Crates

# ===== Daily commands =====
cargo new myapp            # binary
cargo new mylib --lib      # library
cargo build                # debug
cargo build --release      # optimised
cargo run                  # build + run
cargo test                 # run tests
cargo check                # type-check without codegen (fast)
cargo clippy               # lint
cargo fmt                  # format
cargo doc --open           # generate + open API docs

# ===== Cargo.toml =====
[package]
name = "myapp"
version = "0.1.0"
edition = "2021"
rust-version = "1.78"

[dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[dev-dependencies]
proptest = "1"
criterion = "0.5"

[profile.release]
lto = "thin"
codegen-units = 1

[features]
default = ["json"]
json = ["dep:serde_json"]

# ===== Adding deps without editing TOML =====
cargo add serde --features derive
cargo add tokio -F full
cargo add criterion --dev
cargo remove unused-crate

# ===== Workspaces (multi-crate repo) =====
# Cargo.toml at the root:
[workspace]
members = ["crates/*"]

# crates/util/Cargo.toml + crates/cli/Cargo.toml each a crate.
# Single target/ directory for the workspace; faster incremental builds.

# ===== Features =====
[features]
default = ["std"]
std = []
serde_support = ["serde"]

# Build with non-default features:
cargo build --no-default-features --features serde_support

# ===== Examples + benches + bins =====
# examples/foo.rs       cargo run --example foo
# benches/perf.rs       cargo bench
# src/bin/extra.rs      cargo run --bin extra
# Main bin: src/main.rs (or src/bin/<crate>.rs)

# ===== Releases =====
cargo build --release      # target/release/<bin>
cargo publish               # upload to crates.io (requires login)
cargo install ripgrep       # build + install a binary crate to ~/.cargo/bin

# ===== Cargo.lock =====
# Binaries: commit Cargo.lock for reproducible builds.
# Libraries: usually do NOT commit Cargo.lock (defer to downstream consumers).

# ===== Useful tooling =====
cargo install cargo-edit    # provides cargo add / rm
cargo install cargo-watch   # cargo watch -x test
cargo install cargo-nextest # faster test runner
cargo install cargo-audit   # checks for known vulnerable deps
cargo install cargo-deny    # license / source / advisory checks

# ===== Cross-compile =====
rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl
# Static binary; great for distroless containers.

# ===== Patterns to internalise =====
# - cargo check on save (fast feedback)
# - cargo clippy -- -D warnings in CI
# - Workspaces for multi-crate repos
# - Features instead of conditional cfg sprawl
# - Pin rust-version in Cargo.toml

# ===== Pitfalls =====
# - Forgetting --release when benchmarking (debug is 10-100x slower)
# - Mixing default-features = false + features in dep specs incorrectly
# - Publishing to crates.io with secrets in Cargo.toml
# - Long compile times — measure with cargo +nightly build -Z timings

# Cargo.toml — manifest. crates.io — registry.
[dependencies]
serde = { version = "1", features = ["derive"] }