rust-tooling-guide

What this skill does

You are an expert in modern Rust tooling and development workflows, with comprehensive knowledge of the 2025 Rust ecosystem.

## Your Expertise

You guide developers on:
- Modern development workflow tools
- Code quality and linting tools
- Security scanning and dependency auditing
- Performance profiling and optimization
- Testing frameworks and runners
- CI/CD integration patterns

## Modern Rust Tooling Ecosystem (2025)

### Essential Development Tools

#### 1. Bacon - Background Rust Compiler

**What it is:** A background compiler that watches your source and shows errors, warnings, and test failures.

**Installation:**
```bash
cargo install --locked bacon
```

**Usage:**
```bash
# Run default check
bacon

# Run with clippy
bacon clippy

# Run tests continuously
bacon test

# Run with nextest
bacon nextest
```

**Why use it:**
- Minimal interaction - runs alongside your editor
- Faster feedback than cargo-watch
- Built specifically for Rust
- Shows exactly what's failing without scrolling

**When to use:**
- During active development
- When refactoring large codebases
- When running tests continuously
- As a complement to rust-analyzer

#### 2. Cargo-nextest - Next-Generation Test Runner

**What it is:** A faster, more reliable test runner with modern execution model.

**Installation:**
```bash
cargo install cargo-nextest
```

**Usage:**
```bash
# Run all tests
cargo nextest run

# Run with output
cargo nextest run --nocapture

# Run specific test
cargo nextest run test_name

# Show test timing
cargo nextest run --timings
```

**Features:**
- Parallel test execution (faster)
- Cleaner output
- Better failure reporting
- Test flakiness detection
- JUnit output for CI

**Important:** Doctests not supported - run separately:
```bash
cargo test --doc
```

**Why use it:**
- Significantly faster than `cargo test`
- Better at detecting flaky tests
- Cleaner CI output
- Per-test timeout support

#### 3. Cargo-watch - Auto-rebuild on Changes

**What it is:** Automatically runs Cargo commands when source files change.

**Installation:**
```bash
cargo install cargo-watch
```

**Usage:**
```bash
# Watch and check
cargo watch -x check

# Watch and test
cargo watch -x test

# Watch and run
cargo watch -x run

# Chain commands
cargo watch -x check -x test -x run

# Clear screen before each run
cargo watch -c -x test
```

**Why use it:**
- Simple and reliable
- Works with any cargo command
- Good for simple projects
- For Rust-specific features, prefer bacon

### Code Quality & Linting

#### 4. Clippy - The Rust Linter

**Built-in:** Comes with Rust installation

**Basic Usage:**
```bash
# Run clippy
cargo clippy

# Treat warnings as errors
cargo clippy -- -D warnings

# Pedantic mode (extra-clean code)
cargo clippy -- -W clippy::pedantic

# Deny all warnings
RUSTFLAGS="-D warnings" cargo clippy
```

**Configuration:** Create `clippy.toml` or `.clippy.toml`:
```toml
# Example clippy.toml
cognitive-complexity-threshold = 30
single-char-binding-names-threshold = 5
too-many-arguments-threshold = 8
```

**Recommended Lints:**
```rust
// In lib.rs or main.rs
#![warn(clippy::all)]
#![warn(clippy::pedantic)]
#![warn(clippy::nursery)]
#![warn(clippy::cargo)]

// Optionally allow some pedantic lints
#![allow(clippy::missing_errors_doc)]
#![allow(clippy::module_name_repetitions)]
```

**CI/CD Integration:**
```yaml
# .github/workflows/ci.yml
- name: Run Clippy
  run: cargo clippy --all-targets --all-features -- -D warnings
```

**Best Practices:**
- Run before every commit
- Enable in CI/CD pipeline
- Use pedantic mode for new projects
- Fix warnings incrementally in legacy code
- Configure rust-analyzer to run clippy on save

#### 5. Rustfmt - Code Formatter

**Configuration:** Create `rustfmt.toml`:
```toml
# Example rustfmt.toml
edition = "2024"
max_width = 100
hard_tabs = false
tab_spaces = 4
imports_granularity = "Crate"
group_imports = "StdExternalCrate"
```

**Usage:**
```bash
# Format all files
cargo fmt

# Check without formatting
cargo fmt -- --check

# Format specific file
rustfmt src/main.rs
```

### Security & Supply Chain Tools

#### 6. Cargo-audit - Security Vulnerability Scanner

**What it is:** Scans dependencies against RustSec Advisory Database

**Installation:**
```bash
cargo install cargo-audit
```

**Usage:**
```bash
# Audit dependencies
cargo audit

# Audit with JSON output
cargo audit --json

# Fix advisories (update Cargo.toml)
cargo audit fix
```

**CI/CD Integration:**
```yaml
- name: Security Audit
  run: cargo audit
```

**Why use it:**
- Catches known vulnerabilities
- Official RustSec integration
- Essential for production code
- Should run in every CI pipeline

#### 7. Cargo-deny - Dependency Linter

**What it is:** Checks dependencies, licenses, sources, and security advisories

**Installation:**
```bash
cargo install cargo-deny
```

**Setup:**
```bash
# Initialize configuration
cargo deny init
```

**This creates `deny.toml`:**
```toml
[advisories]
vulnerability = "deny"
unmaintained = "warn"

[licenses]
unlicensed = "deny"
allow = ["MIT", "Apache-2.0", "BSD-3-Clause"]

[bans]
multiple-versions = "warn"
deny = [
    { name = "openssl" },  # Example: ban specific crates
]

[sources]
unknown-registry = "deny"
unknown-git = "deny"
```

**Usage:**
```bash
# Check everything
cargo deny check

# Check specific category
cargo deny check advisories
cargo deny check licenses
cargo deny check bans
cargo deny check sources
```

**Why use it:**
- License compliance
- Security scanning
- Duplicate dependency detection
- Source verification
- More comprehensive than cargo-audit

#### 8. Cargo-semver-checks - SemVer Violation Checker

**What it is:** Ensures your API changes follow semantic versioning

**Installation:**
```bash
cargo install cargo-semver-checks
```

**Usage:**
```bash
# Check current version
cargo semver-checks

# Check against specific version
cargo semver-checks check-release --baseline-version 1.2.0
```

**Why use it:**
- Catches breaking changes before release
- Found violations in 1 in 6 top crates
- Being integrated into cargo
- Essential for library authors

**CI/CD Integration:**
```yaml
- name: Check SemVer
  run: cargo semver-checks check-release
```

### Performance & Profiling

#### 9. Cargo-flamegraph - Visual Performance Profiler

**What it is:** Generates flamegraphs for performance analysis

**Installation:**
```bash
cargo install flamegraph
```

**Usage:**
```bash
# Profile default binary
cargo flamegraph

# Profile with arguments
cargo flamegraph -- arg1 arg2

# Profile specific binary
cargo flamegraph --bin=mybin

# Profile with custom perf options
cargo flamegraph -c "cache-misses"
```

**Important:** Enable debug symbols in release mode:
```toml
[profile.release]
debug = true
```

Or use environment variable:
```bash
CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph
```

**Why use it:**
- Visual performance bottleneck identification
- Works on Linux and macOS (DTrace)
- One team cut CPU usage by 70% using flamegraphs
- Essential for optimization work

**Alternative:** `samply` - More interactive UI with Firefox Profiler integration

### Additional Useful Tools

#### 10. Cargo-machete - Unused Dependency Remover

```bash
cargo install cargo-machete
cargo machete
```

**Why:** Finds and removes unused dependencies, reducing build times and attack surface

#### 11. Cargo-udeps - Unused Dependencies (requires nightly)

```bash
cargo +nightly install cargo-udeps
cargo +nightly udeps
```

#### 12. Cargo-outdated - Check for Outdated Dependencies

```bash
cargo install cargo-outdated
cargo outdated
```

## Recommended Development Workflow

### Local Development Setup

```bash
# Install essential tools
cargo install bacon
cargo install cargo-nextest
cargo install cargo-audit
cargo install cargo-deny
cargo install flamegraph

# Initialize cargo-deny
cargo deny init

# Create clippy config
cat > clippy.toml << EOF
cognitive-complexity-threshold = 30
EOF

# Create rustfmt config
cat > rustfmt.toml << EOF
edition = "2024"
ma