existential-birds/beagle / plugins/beagle-rust/skills/rust-project-setup
rust-project-setup
VerifiedGuidance for scaffolding new Rust projects. Use when: (1) starting a new Rust project or workspace, (2) configuring Cargo.toml best practices, (3) setting up CI pipelines for Rust, (4) organizing a multi-crate workspace, (5) configuring clippy, rustfmt, and linting.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.4 KB |
| references/cargo-config.md | markdown | 10.3 KB |
| references/ci-setup.md | markdown | 6.0 KB |
| references/features-conditional.md | markdown | 11.6 KB |
| references/no-std.md | markdown | 5.6 KB |
| references/workspace-layout.md | markdown | 10.1 KB |
references/cargo-config.md
View on GitHub# Cargo.toml Configuration
## Package Metadata
```toml
[package]
name = "my-crate"
version = "0.1.0"
edition = "2024" # latest stable edition
rust-version = "1.85" # minimum supported Rust version (MSRV)
description = "What this crate does"
license = "MIT OR Apache-2.0"
repository = "https://github.com/org/repo"
```
### Edition Selection
| Edition | When to Use |
|---------|-------------|
| 2024 | New projects (latest, best defaults) |
| 2021 | Projects supporting older Rust versions |
| 2018 | Legacy compatibility only |
Each edition enables new language features and changes some defaults. Editions are opt-in and backward compatible.
#### Edition 2024 Key Behavioral Changes
- **`unsafe_op_in_unsafe_fn` = deny**: Unsafe operations inside `unsafe fn` require explicit `unsafe {}` blocks
- **`unsafe extern` blocks**: `extern "C" {}` must be `unsafe extern "C" {}`
- **`unsafe` attributes**: `#[no_mangle]` becomes `#[unsafe(no_mangle)]`, same for `#[export_name]`
- **`gen` keyword reserved**: Use `r#gen` if you have identifiers named `gen`
- **RPIT lifetime capture**: `-> impl Trait` captures all in-scope lifetimes; use `+ use<'a, T>` for precise control
- **`never_type_fallback`**: `!` falls back to `!` instead of `()`
- **Temporary drop scopes**: Temporaries in `if let` conditions and tail expressions drop earlier
- **`IntoIterator` for `Box<[T]>`**: Now available without explicit conversion
Run `cargo fix --edition` to auto-migrate most mechanical changes when upgrading.
### MSRV (Minimum Supported Rust Version)
Set `rust-version` to declare the oldest Rust version your crate supports. CI should test against this version.
```toml
rust-version = "1.85"
```
## Dependencies
### Version Specification
```toml
[dependencies]
# Libraries: semver range (compatible updates)
serde = "1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
# Binaries: exact pinning (reproducible builds)
reqwest = "=0.12.5"
# Git dependencies (development only, never publish with these)
my-fork = { git = "https://github.com/user/fork", branch = "fix" }
# Path dependencies (workspace members)
shared-types = { path = "../shared-types" }
[dev-dependencies]
insta = { version = "1", features = ["yaml"] }
rstest = "0.23"
pretty_assertions = "1"
tokio = { version = "1", features = ["test-util"] }
[build-dependencies]
# Only for build.rs scripts
```
### Version Specifier Patterns
| Specifier | Meaning | Use When |
|-----------|---------|----------|
| `"1"` | `>=1.0.0, <2.0.0` | Library deps (wide compatibility) |
| `"1.4"` | `>=1.4.0, <2.0.0` | You need features added in 1.4 |
| `"1.4.3"` (or `"^1.4.3"`) | `>=1.4.3, <2.0.0` | Default caret behavior |
| `"~1.4.3"` | `>=1.4.3, <1.5.0` | Lock to a specific minor version |
| `"=1.4.3"` | Exactly `1.4.3` | Binary pinning, reproducibility |
| `">=1.4, <1.7"` | Range | Avoid known-broken versions |
Set the **minimum version that actually works**, not the latest. Use `cargo +nightly -Zminimal-versions check` to verify your lower bounds are correct. If your code needs something added in 1.6, don't specify `"1"` when `"1.6"` is the honest minimum.
### Patching Dependencies
Override any dependency source temporarily for testing fixes or unreleased changes:
```toml
[patch.crates-io]
regex = { path = "/home/dev/regex" }
serde = { git = "https://github.com/serde-rs/serde.git", branch = "fix" }
```
Patches apply globally across the dependency graph but are not carried into published crates. Use for development only.
### Feature Flags
Define optional features to reduce compile time and binary size:
```toml
[features]
default = ["json"]
json = ["dep:serde_json"]
full = ["json", "yaml", "toml-support"]
yaml = ["dep:serde_yaml"]
toml-support = ["dep:toml"]
```
Use `dep:` prefix (Rust 1.60+) to avoid implicit feature names from optional dependencies.
### Feature Composability Rules
Features must be **additive**. Enabling a feature should never remove types, modules, or function signatures. Cargo takes the **union** of all requested features when multiple crates depend on the same dependency with different features — mutually exclusive features break downstream builds.
Key gotchas:
- **Conditional public items**: If a public struct field or enum variant is gated by a feature, mark the type `#[non_exhaustive]`. Otherwise, dependents without the feature may stop compiling when another crate enables it.
- **Feature-gated trait impls**: Adding a trait impl behind a feature is safe. Removing one is breaking.
- **Test all combinations**: Use `cargo hack check --feature-powerset --no-dev-deps` to verify every combination compiles.
### Workspace Dependency Inheritance
Define dependency versions once at the workspace root, reference in members:
```toml
# Root Cargo.toml
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
tracing = "0.1"
```
```toml
# Member Cargo.toml
[dependencies]
serde.workspace = true
tokio = { workspace = true, features = ["test-util"] } # extend features per-member
```
Members can add features on top of the workspace baseline. Version and base features stay consistent across the workspace.
### Deprecated Dependency Replacements
With Rust 1.80+ (required for edition 2024), several popular crates have stdlib replacements:
| Crate | Replacement | Since |
|-------|-------------|-------|
| `once_cell` | `std::sync::LazyLock`, `std::cell::LazyCell` | 1.80 |
| `lazy_static` | `std::sync::LazyLock` | 1.80 |
```rust
// BAD: external dependency for edition 2024 projects
use once_cell::sync::Lazy;
static CONFIG: Lazy<Config> = Lazy::new(|| Config::load());
// GOOD: stdlib LazyLock (stable since 1.80)
use std::sync::LazyLock;
static CONFIG: LazyLock<Config> = LazyLock::new(|| Config::load());
```
## Profiles
### Release Profile
```toml
[profile.release]
lto = true # link-time optimization (slower build, faster binary)
codegen-units = 1 # single codegen unit (slower build, better optimization)
strip = true # strip debug symbols (smaller binary)
panic = "abort" # smaller binary, no unwinding (not for libraries)
```
### Development Profile
```toml
[profile.dev]
opt-level = 0 # fast compilation (default)
[profile.dev.package."*"]
opt-level = 2 # optimize dependencies but not your code
```
### Test Profile
```toml
[profile.test]
opt-level = 1 # slightly faster test execution
```
### Custom Profiles
Define profiles beyond dev/release for specialized builds:
```toml
[profile.profiling]
inherits = "release"
debug = true # debug symbols for perf/flamegraph
strip = false
[profile.embedded]
inherits = "release"
opt-level = "s" # optimize for binary size
lto = true
codegen-units = 1
panic = "abort"
```
Use with `cargo build --profile profiling`. Each profile gets its own `target/<profile-name>/` output directory.
### Per-Dependency Profile Overrides
Optimize specific dependencies differently from your own code:
```toml
[profile.dev.package.serde]
opt-level = 3 # full optimization for serde even in debug
[profile.dev.package."*"]
opt-level = 2 # moderate optimization for all other deps
```
Useful when a dependency is prohibitively slow in debug mode (compression, video encoding, crypto). Note: generic code monomorphized in your crate uses your crate's profile settings, not the dependency override.
## Supply Chain Auditing with cargo-deny
Configure `cargo-deny` for automated dependency auditing in CI:
```shell
cargo install cargo-deny
cargo deny init # creates deny.toml
cargo deny check # run all checks
```
```toml
# deny.toml
[licenses]
allow = ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause"]
[bans]
multiple-versions = "warn"
wildcards = "deny"
[advisories]
vulnerability = "deny"
unmaintained = "warn"
[sources]
allow-git = []
```
Also run `cargo audit` for security vulnerability checks. Both tools complement each other: `cargo-deny` covers licenses and duplicates, `cargo-audit` focuses on CVEs.
## Clippy and Lint Configuration
### Package-Level Lints
```toml
[lints.clippy]
all = { level = "deny", priority = 10 }
redundant_clone = { level = "deny", priority = 9 }
pedantic = { level = "warn", priority = 3 }
[lints.rust]
future-incompatible = "warn"
nonstandard_style = "deny"
unsafe_code = "deny" # for crates that should never use unsafe
# unsafe_op_in_unsafe_fn is deny-by-default in edition 2024 — no explicit entry needed
```
#### Edition 2024 Lint Defaults
These lints are deny-by-default in edition 2024 and do not need explicit configuration:
| Lint | Effect |
|------|--------|
| `unsafe_op_in_unsafe_fn` | Unsafe ops in `unsafe fn` require explicit `unsafe {}` blocks |
| `never_type_fallback_flowing_into_unsafe` | Prevents `!` fallback into unsafe contexts |
Use `#[expect(lint)]` instead of `#[allow(lint)]` for temporary suppressions — it warns when the suppression becomes unnecessary:
```rust
#[expect(clippy::needless_pass_by_value, reason = "required by framework trait")]
fn handler(req: Request) -> Response { /* ... */ }
```
### Workspace-Level Lints
Define once, inherit everywhere:
```toml
# Root Cargo.toml
[workspace.lints.clippy]
all = { level = "deny", priority = 10 }
pedantic = { level = "warn", priority = 3 }
```
```toml
# Member Cargo.toml
[lints]
workspace = true
```
## rustfmt.toml
```toml
edition = "2024"
max_width = 100
reorder_imports = true
imports_granularity = "Crate"
group_imports = "StdExternalCrate"
use_field_init_shorthand = true
```
Place in the repository root. Runs automatically with `cargo fmt`.
## Cargo.lock Policy
| Project Type | Commit Cargo.lock? | Reason |
|-------------|-------------------|--------|
| Binary / Application | Yes | Reproducible builds |
| Library | No | Consumers resolve their own versions |
| Workspace with binaries | Yes | Binary members need reproducible builds |
For libraries, add to `.gitignore`:
```gitignore
Cargo.lock
```
## Useful Commands
```shell
cargo check # fast type checking without building
cargo build --release # optimized build
cargo test # run all tests
cargo doc --open # generate and view documentation
cargo tree # show dependency tree
cargo audit # check for security vulnerabilities
cargo update # update dependencies within semver constraints
cargo clippy --fix # auto-fix clippy suggestions
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |