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

toml
1[workspace]
2members = [
3    "crate1",
4    "crate2",
5    "crate3",
6]
7resolver = "2"  # or "3" for newer editions

Workspace Package Inheritance

toml
1[workspace]
2members = ["crate1", "crate2"]
3
4[workspace.package]
5version = "0.1.0"
6edition = "2021"
7authors = ["Author Name"]
8license = "MIT"
9
10# Individual crates inherit these values
11[package]
12name = "crate1"
13# version, edition, authors, license inherited from workspace

Workspace Dependencies

toml
1[workspace.dependencies]
2serde = { version = "1.0", features = ["derive"] }
3tokio = { version = "1.0", features = ["full"] }
4
5# In member crates, use workspace = true
6[dependencies]
7serde = { workspace = true }
8tokio = { workspace = true }

Dependency Management

Version Specifiers

toml
1[dependencies]
2# Exact version
3crate = "1.2.3"
4
5# Compatible version (^1.2.3 = >=1.2.3, <2.0.0)
6crate = "^1.2.3"
7
8# Patch version (~1.2.3 = >=1.2.3, <1.3.0)
9crate = "~1.2.3"
10
11# Wildcard (any version)
12crate = "*"
13
14# Version range
15crate = ">=1.2.0, <2.0.0"

Dependency Sources

toml
1# From crates.io (default)
2crate = "1.0"
3
4# From git repository
5crate = { git = "https://github.com/user/repo", branch = "main" }
6crate = { git = "https://github.com/user/repo", tag = "v1.0.0" }
7crate = { git = "https://github.com/user/repo", rev = "abc123" }
8
9# From local path
10crate = { path = "../local-crate" }
11
12# From workspace
13crate = { workspace = true }
14
15# With features
16crate = { version = "1.0", features = ["feature1", "feature2"] }
17
18# Optional dependency
19crate = { version = "1.0", optional = true }

Dev Dependencies

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

Build Dependencies

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

Common Cargo Commands

Building

bash
1# Build in debug mode
2cargo build
3
4# Build in release mode
5cargo build --release
6
7# Build specific package
8cargo build --package <package-name>
9
10# Build with features
11cargo build --features <feature-name>
12
13# Build without default features
14cargo build --no-default-features
15
16# Build all workspace members
17cargo build --workspace

Testing

bash
1# Run all tests
2cargo test
3
4# Run tests for specific package
5cargo test --package <package-name>
6
7# Run specific test
8cargo test test_name
9
10# Run tests with output
11cargo test -- --nocapture
12
13# Run tests with features
14cargo test --features <feature-name>

Checking

bash
1# Check code without building
2cargo check
3
4# Check all targets
5cargo check --all-targets
6
7# Check with features
8cargo check --features <feature-name>

Formatting

bash
1# Format code
2cargo fmt
3
4# Check formatting
5cargo fmt --check
6
7# Format workspace
8cargo fmt --workspace

Clippy

bash
1# Run clippy
2cargo clippy
3
4# Run clippy with all targets
5cargo clippy --all-targets --all-features
6
7# Fix issues automatically
8cargo clippy --fix --allow-dirty
9
10# Deny warnings
11cargo clippy -- -D warnings

Documentation

bash
1# Generate documentation
2cargo doc
3
4# Open documentation in browser
5cargo doc --open
6
7# Generate docs for specific package
8cargo doc --package <package-name>
9
10# Generate docs without dependencies
11cargo doc --no-deps
12
13# Generate docs for workspace
14cargo doc --workspace

Dependency Management

bash
1# Update dependencies
2cargo update
3
4# Update specific dependency
5cargo update -p <crate-name>
6
7# Show dependency tree
8cargo tree
9
10# Show dependency tree for specific package
11cargo tree --package <package-name>
12
13# Show only direct dependencies
14cargo tree --depth 1
15
16# Show what depends on a crate
17cargo tree --invert -p <crate-name>

Workspace Metadata Scripts

toml
1[workspace.metadata.scripts]
2build = "cargo build --workspace"
3test = "cargo test --workspace"
4check = "cargo check --workspace"
5clippy = "cargo clippy --workspace"
6fmt = "cargo fmt --workspace"

Package Metadata

toml
1[package]
2name = "my-crate"
3version = "0.1.0"
4edition = "2021"
5authors = ["Author"]
6license = "MIT"
7description = "Description of the crate"
8repository = "https://github.com/user/repo"
9keywords = ["keyword1", "keyword2"]
10categories = ["category1"]
11readme = "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

toml
1[workspace]
2members = ["crate1", "crate2"]
3
4[workspace.dependencies]
5serde = { version = "1.0", features = ["derive"] }
6
7[package]
8name = "crate1"
9serde = { workspace = true }

❌ Avoid

toml
1# Don't duplicate versions
2[package]
3serde = "1.0"  # BAD: Should use workspace
4
5# Don't use wildcard versions in production
6[dependencies]
7crate = "*"  # BAD: Unpredictable updates