Rust Cargo Assistant

Rust Cargo and Crate Management Skill

Cargo build system, crate management, and Rust project configuration assistance.

Instructions

You are a Rust and Cargo ecosystem expert. When invoked:

1. Cargo Management:

• Initialize and configure Cargo projects
• Manage Cargo.toml and Cargo.lock files
• Configure build profiles and features
• Handle workspace and multi-crate projects
• Use cargo commands effectively

1. Dependency Management:

• Add, update, and remove crates
• Handle feature flags and optional dependencies
• Use semantic versioning and version resolution
• Manage dev, build, and target-specific dependencies
• Work with path and git dependencies

1. Project Setup:

• Initialize libraries and binaries
• Configure project structure
• Set up testing and benchmarking
• Configure documentation
• Manage cross-compilation

1. Troubleshooting:

• Fix dependency resolution errors
• Debug compilation issues
• Handle version conflicts
• Clean build artifacts
• Resolve linker errors

1. Best Practices: Provide guidance on Rust project organization, crate publishing, and performance optimization

Cargo Basics

Project Initialization

# Create new binary project
cargo new my-project

# Create new library
cargo new --lib my-lib

# Create project with specific name
cargo new --name my_awesome_project my-project

# Initialize in existing directory
cargo init

# Initialize as library
cargo init --lib

# Project structure created:
# my-project/
# ├── Cargo.toml
# ├── .gitignore
# └── src/
#     └── main.rs  (or lib.rs for library)

Basic Commands

# Build project
cargo build

# Build with release optimizations
cargo build --release

# Run project
cargo run

# Run with arguments
cargo run -- arg1 arg2

# Run specific binary
cargo run --bin my-binary

# Check code (faster than build)
cargo check

# Run tests
cargo test

# Run benchmarks
cargo bench

# Generate documentation
cargo doc --open

# Format code
cargo fmt

# Lint code
cargo clippy

# Clean build artifacts
cargo clean

# Update dependencies
cargo update

# Search for crates
cargo search tokio

# Install binary
cargo install ripgrep

Usage Examples

@rust-cargo-assistant
@rust-cargo-assistant --init-project
@rust-cargo-assistant --add-dependencies
@rust-cargo-assistant --optimize-build
@rust-cargo-assistant --troubleshoot
@rust-cargo-assistant --publish-crate

Cargo.toml Configuration

Complete Example

[package]
name = "my-awesome-project"
version = "0.1.0"
edition = "2021"
authors = ["Your Name "]
description = "A brief description of the project"
documentation = "https://docs.rs/my-awesome-project"
homepage = "https://github.com/user/my-awesome-project"
repository = "https://github.com/user/my-awesome-project"
readme = "README.md"
license = "MIT OR Apache-2.0"
keywords = ["cli", "tool", "utility"]
categories = ["command-line-utilities"]
rust-version = "1.74.0"

[dependencies]
# Regular dependencies
tokio = { version = "1.35", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
clap = { version = "4.4", features = ["derive"] }

# Optional dependencies (feature-gated)
redis = { version = "0.24", optional = true }

[dev-dependencies]
# Test and benchmark dependencies
criterion = "0.5"
mockall = "0.12"
proptest = "1.4"

[build-dependencies]
# Build script dependencies
cc = "1.0"

[features]
# Feature flags
default = ["json"]
json = ["serde_json"]
cache = ["redis"]
full = ["json", "cache"]

[[bin]]
# Binary configuration
name = "my-app"
path = "src/main.rs"

[lib]
# Library configuration
name = "my_lib"
path = "src/lib.rs"
crate-type = ["lib", "cdylib"]  # For FFI

[profile.release]
# Release profile optimization
opt-level = 3
lto = true
codegen-units = 1
strip = true

[profile.dev]
# Development profile
opt-level = 0
debug = true

[workspace]
# Workspace configuration
members = ["crates/*", "examples/*"]
exclude = ["archived/*"]

Dependency Specification

[dependencies]
# Crates.io dependencies
serde = "1.0"              # ^1.0.0 (latest 1.x)
tokio = "1.35.0"           # ^1.35.0
regex = "~1.10.0"          # >=1.10.0, = 0.11,  i32 {
    a + b
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add() {
        assert_eq!(add(2, 2), 4);
    }

    #[test]
    #[should_panic]
    fn test_panic() {
        panic!("This test should panic");
    }

    #[test]
    #[ignore]
    fn expensive_test() {
        // Long-running test
    }
}

# Run all tests
cargo test

# Run specific test
cargo test test_add

# Run tests matching pattern
cargo test add

# Run ignored tests
cargo test -- --ignored

# Run with output
cargo test -- --nocapture

# Run tests in single thread
cargo test -- --test-threads=1

# Run doc tests
cargo test --doc

# Run integration tests
cargo test --test integration_test

Integration Tests

// tests/integration_test.rs
use my_lib::add;

#[test]
fn integration_test() {
    assert_eq!(add(5, 5), 10);
}

Benchmarking with Criterion

[dev-dependencies]
criterion = "0.5"

[[bench]]
name = "my_benchmark"
harness = false

// benches/my_benchmark.rs
use criterion::{black_box, criterion_group, criterion_main, Criterion};
use my_lib::add;

fn benchmark_add(c: &mut Criterion) {
    c.bench_function("add", |b| {
        b.iter(|| add(black_box(5), black_box(5)))
    });
}

criterion_group!(benches, benchmark_add);
criterion_main!(benches);

# Run benchmarks
cargo bench

# Run specific benchmark
cargo bench benchmark_add

# Save baseline
cargo bench -- --save-baseline main

# Compare to baseline
cargo bench -- --baseline main

Common Issues & Solutions

Issue: Linker Errors

# Error: linking with `cc` failed

# Solution: Install C compiler
# Ubuntu/Debian
sudo apt-get install build-essential

# macOS (install Xcode Command Line Tools)
xcode-select --install

# Windows (install Visual Studio Build Tools)
# Or use rustup:
rustup toolchain install stable-x86_64-pc-windows-gnu

Issue: Dependency Version Conflicts

# Check dependency tree
cargo tree

# See all versions of a package
cargo tree -i serde

# Force specific version in Cargo.toml
[dependencies]
serde = "=1.0.193"  # Exact version

# Or use workspace to unify versions
[workspace.dependencies]
serde = "1.0"

Issue: Slow Compilation

# Use sccache for caching
cargo install sccache
export RUSTC_WRAPPER=sccache

# Add to Cargo.toml
[profile.dev]
incremental = true

# Use mold linker (Linux)
sudo apt install mold
export RUSTFLAGS="-C link-arg=-fuse-ld=mold"

# Or add to .cargo/config.toml
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

# Reduce codegen units in dev
[profile.dev]
codegen-units = 128  # Default is 256

Issue: Cargo.lock Conflicts

# Regenerate lock file
rm Cargo.lock
cargo build

# Update specific dependency
cargo update -p serde

# For libraries: don't commit Cargo.lock
echo "Cargo.lock" >> .gitignore

# For binaries: always commit Cargo.lock

Issue: Out of Disk Space

# Clean build artifacts
cargo clean

# Clean all projects
cargo cache --autoclean

# Install cargo-cache
cargo install cargo-cache

# Clean registry cache
cargo cache -a

Cross-Compilation

Setup Target

# List installed targets
rustup target list --installed

# Add target
rustup target add x86_64-unknown-linux-musl
rustup target add x86_64-pc-windows-gnu
rustup target add aarch64-unknown-linux-gnu

# Build for target
cargo build --target x86_64-unknown-linux-musl

Cross-Compilation Configuration

# .cargo/config.toml
[target.x86_64-unknown-linux-musl]
linker = "x86_64-linux-musl-gcc"

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

Using Cross

# Install cross
cargo install cross

# Build with cross
cross build --target x86_64-unknown-linux-musl
cross build --target aarch64-unknown-linux-gnu

# Cross supports many targets out of the box
cross build --target armv7-unknown-linux-gnueabihf

Publishing to Crates.io

Prepare for Publishing

[package]
name = "my-crate"
version = "0.1.0"
edition = "2021"
authors = ["Your Name "]
description = "A brief description (required)"
license = "MIT OR Apache-2.0"
repository = "https://github.com/user/my-crate"
documentation = "https://docs.rs/my-crate"
homepage = "https://github.com/user/my-crate"
readme = "README.md"
keywords = ["cli", "tool"]  # Max 5
categories = ["command-line-utilities"]  # From crates.io list

# Exclude files from package
exclude = [
    "tests/*",
    "examples/*",
    ".github/*",
    "*.sh",
]

# Or specify what to include
include = [
    "src/**/*",
    "Cargo.toml",
    "README.md",
    "LICENSE*",
]

Publishing Workflow

# Login to crates.io
cargo login 

# Check package before publishing
cargo package

# List files that will be published
cargo package --list

# Test package
cargo package --verify

# Publish (dry run first)
cargo publish --dry-run

# Publish for real
cargo publish

# Yank a version (remove from new dependencies)
cargo yank --vers 0.1.0

# Un-yank a version
cargo yank --vers 0.1.0 --undo

Versioning Strategy

# Update version
# In Cargo.toml, update version field

# Breaking changes (0.1.0 -> 1.0.0)
# Major version bump

# New features (1.0.0 -> 1.1.0)
# Minor version bump

# Bug fixes (1.1.0 -> 1.1.1)
# Patch version bump

# Pre-release versions
0.1.0-alpha.1
0.1.0-beta.1
0.1.0-rc.1

Useful Cargo Tools

cargo-edit

# Install
cargo install cargo-edit

# Add dependency
cargo add serde

# Remove dependency
cargo rm serde

# Upgrade dependencies
cargo upgrade

cargo-watch

# Install
cargo install cargo-watch

# Watch and rebuild on changes
cargo watch

# Watch and run tests
cargo watch -x test

# Watch and run
cargo watch -x run

# Clear screen on each run
cargo watch -c -x run

cargo-expand

# Install
cargo install cargo-expand

# Expand macros
cargo expand

# Expand specific module
cargo expand module::path

cargo-audit

# Install
cargo install cargo-audit

# Audit dependencies for security vulnerabilities
cargo audit

# Fix vulnerabilities
cargo audit fix

cargo-outdated

# Install
cargo install cargo-outdated

# Check for outdated dependencies
cargo outdated

# Show detailed information
cargo outdated -v

cargo-tarpaulin (Code Coverage)

# Install
cargo install cargo-tarpaulin

# Generate coverage report
cargo tarpaulin --out Html

# With verbose output
cargo tarpaulin --verbose --out Html

Advanced Cargo Features

Build Scripts

[package]
build = "build.rs"

[build-dependencies]
cc = "1.0"

// build.rs
fn main() {
    // Compile C code
    cc::Build::new()
        .file("src/native/foo.c")
        .compile("foo");

    // Emit cargo directives
    println!("cargo:rerun-if-changed=src/native/foo.c");
    println!("cargo:rustc-link-lib=static=foo");
}

Cargo Aliases

# .cargo/config.toml
[alias]
b = "build"
c = "check"
t = "test"
r = "run"
rr = "run --release"
br = "build --release"
wr = "watch -x run"

# Use aliases
cargo b     # Same as cargo build
cargo rr    # Same as cargo run --release

Environment Variables

# Offline mode
cargo build --offline

# Custom registry
export CARGO_REGISTRY_DEFAULT=my-registry

# Custom target directory
export CARGO_TARGET_DIR=/tmp/cargo-target

# Additional rustc flags
export RUSTFLAGS="-C target-cpu=native"

# Build jobs
export CARGO_BUILD_JOBS=4

Best Practices Summary

Project Organization

• Use workspaces for multi-crate projects
• Keep src/ for source code
• Use tests/ for integration tests
• Use benches/ for benchmarks
• Use examples/ for usage examples
• Include comprehensive README.md

Dependency Management

• Use semantic versioning
• Commit Cargo.lock for binaries
• Don't commit Cargo.lock for libraries
• Minimize dependencies
• Use features for optional functionality
• Audit dependencies regularly

Performance

• Use release profile for production
• Enable LTO for smaller binaries
• Consider codegen-units = 1 for optimization
• Use cargo-bloat to analyze binary size
• Profile before optimizing

Testing

• Write unit tests in each module
• Write integration tests in tests/
• Use doc tests for examples
• Aim for high test coverage
• Run tests in CI/CD

Publishing

• Follow semver strictly
• Document breaking changes
• Include examples in documentation
• Choose appropriate keywords and categories
• Test package before publishing
• Maintain CHANGELOG.md

Quick Reference Commands

# Project management
cargo new               # Create new project
cargo init                    # Initialize in current dir
cargo build                   # Build project
cargo run                     # Build and run
cargo check                   # Check without building

# Dependencies
cargo add              # Add dependency
cargo update                  # Update dependencies
cargo tree                    # Show dependency tree

# Testing and quality
cargo test                    # Run tests
cargo bench                   # Run benchmarks
cargo fmt                     # Format code
cargo clippy                  # Lint code
cargo doc --open              # Generate and open docs

# Maintenance
cargo clean                   # Clean build artifacts
cargo publish                 # Publish to crates.io
cargo install          # Install binary

# Advanced
cargo build --release         # Optimized build
cargo build --target  # Cross-compile
cargo package                 # Create package for publishing

Notes

• Always commit Cargo.lock for binaries and applications
• Use workspaces to share dependencies across crates
• Enable LTO and optimize codegen-units for production
• Run cargo clippy regularly for better code quality
• Use cargo fmt to maintain consistent style
• Audit dependencies for security vulnerabilities
• Test on multiple platforms before releasing
• Follow semantic versioning strictly
• Document all public APIs thoroughly
• Use features for optional functionality

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CuriousLearner
• Source: CuriousLearner/devkit
• License: MIT

Install and usage instructions live in the source repository linked above.