rust-cargo

name	rust-cargo
description	Work with Cargo commands, workspace configuration, dependency management, and build systems. Use when managing dependencies, configuring workspaces, building projects, running tests, or publishing crates. Handles Cargo.toml configuration, workspace setup, dependency resolution, and build commands.

Cargo and Workspace Management

Guidelines for working with Cargo, workspaces, dependencies, and build configuration.

When to Use This Skill

• Managing dependencies in Cargo.toml
• Configuring Rust workspaces
• Understanding dependency resolution
• Building and testing projects
• Publishing crates
• Working with feature flags
• Understanding workspace inheritance

Workspace Configuration

Basic Workspace

[workspace]
members = [
    "crate1",
    "crate2",
    "crate3",
]
resolver = "2"  # or "3" for newer editions

Workspace Package Inheritance

[workspace]
members = ["crate1", "crate2"]

[workspace.package]
version = "0.1.0"
edition = "2021"
authors = ["Author Name"]
license = "MIT"

# Individual crates inherit these values
[package]
name = "crate1"
# version, edition, authors, license inherited from workspace

Workspace Dependencies

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }

# In member crates, use workspace = true
[dependencies]
serde = { workspace = true }
tokio = { workspace = true }

Dependency Management

Version Specifiers

[dependencies]
# Exact version
crate = "1.2.3"

# Compatible version (^1.2.3 = >=1.2.3, <2.0.0)
crate = "^1.2.3"

# Patch version (~1.2.3 = >=1.2.3, <1.3.0)
crate = "~1.2.3"

# Wildcard (any version)
crate = "*"

# Version range
crate = ">=1.2.0, <2.0.0"

Dependency Sources

# From crates.io (default)
crate = "1.0"

# From git repository
crate = { git = "https://github.com/user/repo", branch = "main" }
crate = { git = "https://github.com/user/repo", tag = "v1.0.0" }
crate = { git = "https://github.com/user/repo", rev = "abc123" }

# From local path
crate = { path = "../local-crate" }

# From workspace
crate = { workspace = true }

# With features
crate = { version = "1.0", features = ["feature1", "feature2"] }

# Optional dependency
crate = { version = "1.0", optional = true }

Dev Dependencies

[dev-dependencies]
# Only included when building tests/examples/benchmarks
criterion = "0.5"
tempfile = "3.0"

Build Dependencies

[build-dependencies]
# Only included when building build.rs
cc = "1.0"

Common Cargo Commands

Building

# Build in debug mode
cargo build

# Build in release mode
cargo build --release

# Build specific package
cargo build --package <package-name>

# Build with features
cargo build --features <feature-name>

# Build without default features
cargo build --no-default-features

# Build all workspace members
cargo build --workspace

Testing

# Run all tests
cargo test

# Run tests for specific package
cargo test --package <package-name>

# Run specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run tests with features
cargo test --features <feature-name>

Checking

# Check code without building
cargo check

# Check all targets
cargo check --all-targets

# Check with features
cargo check --features <feature-name>

Formatting

# Format code
cargo fmt

# Check formatting
cargo fmt --check

# Format workspace
cargo fmt --workspace

Clippy

# Run clippy
cargo clippy

# Run clippy with all targets
cargo clippy --all-targets --all-features

# Fix issues automatically
cargo clippy --fix --allow-dirty

# Deny warnings
cargo clippy -- -D warnings

Documentation

# Generate documentation
cargo doc

# Open documentation in browser
cargo doc --open

# Generate docs for specific package
cargo doc --package <package-name>

# Generate docs without dependencies
cargo doc --no-deps

# Generate docs for workspace
cargo doc --workspace

Dependency Management

# Update dependencies
cargo update

# Update specific dependency
cargo update -p <crate-name>

# Show dependency tree
cargo tree

# Show dependency tree for specific package
cargo tree --package <package-name>

# Show only direct dependencies
cargo tree --depth 1

# Show what depends on a crate
cargo tree --invert -p <crate-name>

Workspace Metadata Scripts

[workspace.metadata.scripts]
build = "cargo build --workspace"
test = "cargo test --workspace"
check = "cargo check --workspace"
clippy = "cargo clippy --workspace"
fmt = "cargo fmt --workspace"

Package Metadata

[package]
name = "my-crate"
version = "0.1.0"
edition = "2021"
authors = ["Author"]
license = "MIT"
description = "Description of the crate"
repository = "https://github.com/user/repo"
keywords = ["keyword1", "keyword2"]
categories = ["category1"]
readme = "README.md"

Feature Flags

See rust-features skill for detailed feature flag usage.

Important Rules

1. Use workspace dependencies: Share common dependencies via [workspace.dependencies]
2. Inherit workspace values: Use workspace = true for version, edition, authors, license
3. Pin versions carefully: Use ^ for compatible updates, exact versions sparingly
4. Document features: Clearly document what each feature enables
5. Use resolver = "2" or "3": Specify resolver version for workspace
6. Organize dependencies: Group by purpose (core, error handling, serialization, etc.)

Examples from Project

See Cargo.toml for workspace configuration:

• Workspace members
• Workspace package inheritance
• Workspace dependencies
• Workspace metadata scripts

See individual crate Cargo.toml files for:

• Package configuration
• Feature definitions
• Dependency usage with workspace = true

Common Patterns

✅ Good

[workspace]
members = ["crate1", "crate2"]

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

[package]
name = "crate1"
serde = { workspace = true }

❌ Avoid

# Don't duplicate versions
[package]
serde = "1.0"  # BAD: Should use workspace

# Don't use wildcard versions in production
[dependencies]
crate = "*"  # BAD: Unpredictable updates