gh-emillindfors-claude-marketplace-plugins-rust-modern-patterns/skills/rust-tooling-guide/SKILL.md

---
description: Modern Rust tooling ecosystem guide for 2025 - development workflow, testing, security, and profiling tools
---

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"
max_width = 100
imports_granularity = "Crate"
group_imports = "StdExternalCrate"
EOF
```

### Daily Development Workflow

1. **Start bacon in a terminal:**
   ```bash
   bacon clippy
   ```

2. **Write code in your editor**

3. **Before committing:**
   ```bash
   # Format code
   cargo fmt

   # Run clippy
   cargo clippy -- -D warnings

   # Run tests with nextest
   cargo nextest run

   # Check security
   cargo audit
   ```

### CI/CD Pipeline Template

```yaml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Cache dependencies
        uses: Swatinem/rust-cache@v2

      - name: Install nextest
        run: cargo install cargo-nextest

      - name: Check formatting
        run: cargo fmt -- --check

      - name: Run clippy
        run: cargo clippy --all-targets --all-features -- -D warnings

      - name: Run tests
        run: cargo nextest run

      - name: Run doctests
        run: cargo test --doc

      - name: Security audit
        run: |
          cargo install cargo-audit
          cargo audit

      - name: Check licenses
        run: |
          cargo install cargo-deny
          cargo deny check

      - name: SemVer check
        if: github.event_name == 'pull_request'
        run: |
          cargo install cargo-semver-checks
          cargo semver-checks check-release
```

## Tool Selection Guide

### For Active Development
- **bacon** - Continuous feedback while coding
- **cargo-nextest** - Fast test runs
- **clippy (pedantic)** - Catch issues early

### For CI/CD
- **cargo clippy** - Enforce code quality
- **cargo nextest** - Fast, reliable tests
- **cargo audit** - Security scanning
- **cargo deny** - Comprehensive checks
- **cargo semver-checks** - API compatibility

### For Performance Work
- **cargo-flamegraph** - Profile and visualize
- **perf** - Linux performance analysis
- **samply** - Interactive profiling (macOS)

### For Libraries
- **cargo-semver-checks** - Essential for public APIs
- **cargo deny** - License compliance
- **cargo-audit** - Security

### For Applications
- **cargo-audit** - Security
- **cargo-machete** - Reduce dependencies
- **cargo-flamegraph** - Optimize hot paths

## Best Practices

1. **Use bacon during development** - Instant feedback
2. **Run clippy pedantic** - Catch issues early
3. **Use cargo-nextest for tests** - Faster, better output
4. **Audit security weekly** - cargo audit in CI
5. **Check licenses** - cargo deny for compliance
6. **Profile before optimizing** - Use flamegraphs
7. **Check SemVer for libraries** - Prevent breaking changes
8. **Format before commit** - cargo fmt
9. **Cache CI dependencies** - Use rust-cache action
10. **Document tool requirements** - In README

## Configuration Examples

### Complete Project Setup

```toml
# clippy.toml
cognitive-complexity-threshold = 30
single-char-binding-names-threshold = 5
too-many-arguments-threshold = 7

# rustfmt.toml
edition = "2024"
max_width = 100
hard_tabs = false
tab_spaces = 4
imports_granularity = "Crate"
group_imports = "StdExternalCrate"
format_code_in_doc_comments = true

# deny.toml (generated by cargo deny init)
[advisories]
vulnerability = "deny"
unmaintained = "warn"
unsound = "warn"

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

[bans]
multiple-versions = "warn"
wildcards = "warn"
```

### Cargo.toml Additions

```toml
[profile.release]
debug = true  # For profiling

[workspace.metadata.clippy]
warn = ["clippy::all", "clippy::pedantic"]
```

## Troubleshooting

### Bacon not updating
- Ensure you're in project root
- Check file watchers limit: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`

### Nextest issues
- Doctests not supported - run `cargo test --doc` separately
- For integration tests, use `cargo nextest run --workspace`

### Flamegraph empty/incorrect
- Enable debug symbols: `debug = true` in `[profile.release]`
- On Linux, may need perf access: `echo 0 | sudo tee /proc/sys/kernel/perf_event_paranoid`

### Clippy false positives
- Allow specific lints: `#[allow(clippy::lint_name)]`
- Configure thresholds in clippy.toml
- Report false positives to clippy project

## Resources

- [Bacon Documentation](https://dystroy.org/bacon/)
- [Cargo-nextest Guide](https://nexte.st/)
- [Clippy Lints](https://rust-lang.github.io/rust-clippy/)
- [RustSec Database](https://rustsec.org/)
- [Cargo-deny Documentation](https://embarkstudios.github.io/cargo-deny/)
- [Flamegraph Guide](https://github.com/flamegraph-rs/flamegraph)
- [Rust Performance Book](https://nnethercote.github.io/perf-book/)

## Your Role

When helping users with Rust tooling:

1. **Assess their needs** - Development, CI, performance, security?
2. **Recommend appropriate tools** - Based on use case
3. **Provide setup instructions** - Complete, tested commands
4. **Show integration patterns** - CI/CD, pre-commit hooks, etc.
5. **Explain trade-offs** - Why one tool over another
6. **Help troubleshoot** - Common issues and solutions

Always prioritize:
- **Security** - cargo-audit is essential
- **Code quality** - clippy catches real bugs
- **Developer experience** - bacon improves workflow
- **CI efficiency** - nextest saves time
- **Maintainability** - cargo-deny prevents issues

Your goal is to help developers set up modern, efficient Rust development workflows that catch issues early and maintain high code quality.