rust-cargo-assistant

What this skill does

# 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

2. **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

3. **Project Setup**:
   - Initialize libraries and binaries
   - Configure project structure
   - Set up testing and benchmarking
   - Configure documentation
   - Manage cross-compilation

4. **Troubleshooting**:
   - Fix dependency resolution errors
   - Debug compilation issues
   - Handle version conflicts
   - Clean build artifacts
   - Resolve linker errors

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

## Cargo Basics

### Project Initialization
```bash
# 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
```bash
# 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
```toml
[package]
name = "my-awesome-project"
version = "0.1.0"
edition = "2021"
authors = ["Your Name <[email protected]>"]
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
```toml
[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, <1.11.0

# Version operators
reqwest = ">= 0.11, < 0.13"
actix-web = "= 4.4.0"      # Exact version

# Git dependencies
my-lib = { git = "https://github.com/user/my-lib" }
my-lib = { git = "https://github.com/user/my-lib", branch = "main" }
my-lib = { git = "https://github.com/user/my-lib", tag = "v1.0.0" }
my-lib = { git = "https://github.com/user/my-lib", rev = "abc123" }

# Path dependencies (local development)
my-local-lib = { path = "../my-local-lib" }

# Features
tokio = { version = "1.35", features = ["full"] }
serde = { version = "1.0", features = ["derive"], default-features = false }

# Optional dependencies
redis = { version = "0.24", optional = true }

# Renamed dependencies
web-framework = { package = "actix-web", version = "4.4" }

# Platform-specific dependencies
[target.'cfg(windows)'.dependencies]
winapi = "0.3"

[target.'cfg(unix)'.dependencies]
nix = "0.27"

[target.'cfg(target_arch = "wasm32")'.dependencies]
wasm-bindgen = "0.2"
```

## Project Structure Patterns

### Binary Project
```
my-app/
├── Cargo.toml
├── Cargo.lock
├── src/
│   ├── main.rs
│   ├── lib.rs (optional)
│   ├── config.rs
│   └── utils.rs
├── tests/
│   └── integration_test.rs
├── benches/
│   └── benchmark.rs
├── examples/
│   └── example.rs
└── README.md
```

### Library Project
```
my-lib/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── error.rs
│   └── types.rs
├── tests/
│   └── lib_test.rs
├── benches/
│   └── performance.rs
├── examples/
│   └── basic_usage.rs
└── README.md
```

### Workspace Project
```
workspace/
├── Cargo.toml (workspace root)
├── crates/
│   ├── core/
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   ├── api/
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   └── cli/
│       ├── Cargo.toml
│       └── src/main.rs
├── examples/
│   └── demo/
│       ├── Cargo.toml
│       └── src/main.rs
└── README.md
```

```toml
# Workspace Cargo.toml
[workspace]
members = [
    "crates/core",
    "crates/api",
    "crates/cli",
]

[workspace.package]
edition = "2021"
license = "MIT OR Apache-2.0"
rust-version = "1.74.0"

[workspace.dependencies]
# Shared dependency versions
tokio = { version = "1.35", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
```

## Dependency Management

### Adding Dependencies
```bash
# Add latest version
cargo add serde

# Add with features
cargo add tokio --features full

# Add dev dependency
cargo add --dev proptest

# Add build dependency
cargo add --build cc

# Add optional dependency
cargo add redis --optional

# Add from git
cargo add --git https://github.com/user/repo

# Add specific version
cargo add [email protected]
```

### Updating Dependencies
```bash
# Update all dependencies
cargo update

# Update specific dependency
cargo update serde

# Update to breaking version
cargo upgrade

# Check for outdated dependencies
cargo outdated

# Show dependency tree
cargo tree

# Show dependency tree for specific package
cargo tree -p tokio

# Show duplicate dependencies
cargo tree --duplicates

# Explain why dependency is included
cargo tree -i serde
```

### Managing Features
```toml
[features]
default = ["std"]
std = []
async = ["tokio", "async-trait"]
serde = ["dep:serde", "dep:serde_json"]
full = ["std", "async", "serde"]
```

```bash
# Build with specific features
cargo build --features async

# Build with multiple features
cargo build --features "async,serde"

# Build with all features
cargo build --all-features

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

# Build with no default but specific features
cargo build --no-default-features --features std
```

## Build Profiles and Optimization

### Profile Configuration
```toml
[profile.dev]
opt-level = 0              # No optimization
debug = true