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/workspace-layout.md
View on GitHub# Workspace Layout
## When to Use Workspaces
Use a workspace when you have multiple related crates that:
- Share dependencies (reduces compile time and disk usage)
- Need coordinated versioning
- Have separate build targets (binary + library, multiple binaries)
- Benefit from a shared CI pipeline
Don't use a workspace for a single crate. The overhead isn't worth it.
## Basic Structure
```text
my-workspace/
Cargo.toml # workspace root
rustfmt.toml # shared formatting
.github/
workflows/ci.yml # shared CI
crates/
core/ # shared types and logic
Cargo.toml
src/lib.rs
api/ # HTTP server binary
Cargo.toml
src/main.rs
cli/ # CLI binary
Cargo.toml
src/main.rs
tests/ # workspace-level integration tests (optional)
```
## Workspace Cargo.toml
```toml
[workspace]
resolver = "3" # default for edition 2024; explicit for clarity
members = [
"crates/core",
"crates/api",
"crates/cli",
]
[workspace.package]
edition = "2024"
rust-version = "1.85"
license = "MIT"
repository = "https://github.com/org/repo"
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
thiserror = "2"
tracing = "0.1"
[workspace.lints.clippy]
all = { level = "deny", priority = 10 }
pedantic = { level = "warn", priority = 3 }
[workspace.lints.rust]
future-incompatible = "warn"
```
## Member Cargo.toml
Members inherit from workspace:
```toml
[package]
name = "my-api"
version = "0.1.0"
edition.workspace = true
rust-version.workspace = true
license.workspace = true
[dependencies]
my-core = { path = "../core" } # path dependency to workspace member
serde.workspace = true # inherit version and features
tokio.workspace = true
axum = "0.8" # member-specific dependency
[lints]
workspace = true # inherit lint config
```
## Edition Inheritance in Workspaces
Edition 2024 introduces important workspace-level behaviors:
- **Edition inherits from workspace**: Members using `edition.workspace = true` inherit the workspace edition. All members get edition 2024 semantics (unsafe block requirements, lifetime capture rules, etc.)
- **Mixed editions**: Members can override with a local `edition = "2021"` if needed, but this creates inconsistent behavior across crates — avoid when possible
- **Resolver**: Edition 2024 defaults to resolver `"3"` (MSRV-aware); edition 2021 defaults to `"2"`. Setting it explicitly in the workspace root is good practice for clarity
- **Lint inheritance**: `[workspace.lints.rust]` applies uniformly, but edition 2024 deny-by-default lints (like `unsafe_op_in_unsafe_fn`) activate per-member based on that member's edition
```toml
# Root Cargo.toml — all members inherit edition 2024
[workspace.package]
edition = "2024"
rust-version = "1.85"
# Member Cargo.toml — inherits edition 2024 and MSRV
[package]
name = "my-crate"
version = "0.1.0"
edition.workspace = true
rust-version.workspace = true
```
## Shared Dependencies
Define versions once in `[workspace.dependencies]`, reference with `.workspace = true` in members:
```toml
# Root Cargo.toml
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
# Member Cargo.toml
[dependencies]
serde.workspace = true
```
To add features for a specific member:
```toml
[dependencies]
tokio = { workspace = true, features = ["test-util"] }
```
## Path Dependencies
Members reference each other with path dependencies:
```toml
[dependencies]
core = { path = "../core" }
```
These are resolved at build time. Cargo ensures all workspace members use compatible versions.
## Feature Flags Across Workspace
Define features in individual crates and propagate through path dependencies:
```toml
# crates/core/Cargo.toml
[features]
default = []
postgres = ["dep:sqlx"]
metrics = ["dep:prometheus"]
# crates/api/Cargo.toml
[dependencies]
core = { path = "../core", features = ["postgres", "metrics"] }
```
## Running Commands
```shell
# Run across all members
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
# Run for a specific member
cargo test -p my-api
cargo run -p my-cli
# Build specific binary
cargo build --release -p my-api
```
## Common Patterns
### Shared Types Crate
A `core` or `types` crate containing shared types, error definitions, and traits:
```text
crates/core/src/
lib.rs # re-exports
error.rs # shared error types
types.rs # domain types
traits.rs # shared trait definitions
```
### Binary + Library Split
Separate the binary entry point from logic for testability:
```text
crates/api/src/
main.rs # entry point, minimal
lib.rs # all logic, imported by main.rs and tests
```
### Internal Crates
Mark crates as internal (not published) by omitting `version` or adding `publish = false`:
```toml
[package]
name = "internal-utils"
publish = false
```
## Profile Tuning for Release Builds
The default `[profile.release]` leaves serious performance on the table. The knobs that matter for shipped binaries:
- `opt-level = 3` — full optimization (default). Drop to `"s"` or `"z"` only for size-constrained targets (wasm, embedded).
- `lto = "thin"` — parallel cross-crate inlining. The sweet spot for most projects. Use `"fat"` (or `true`) for whole-program LTO when binary size and runtime matter more than build time.
- `codegen-units = 1` — sacrifices build parallelism for better optimization. Combine with LTO. Only worth it for the final shipped artifact.
- `panic = "abort"` — smaller binary, no unwinding tables. **Destructors do not run on panic** and `catch_unwind` becomes a no-op. The setting is global across all deps — audit every dep's reliance on unwinding before flipping.
- `strip = "symbols"` (Cargo 1.59+) — removes debug symbols from the final binary, often shrinking it 50-80%.
```toml
[profile.release]
opt-level = 3 # full speed
lto = "thin" # cross-crate inlining
codegen-units = 1 # max optimization for shipped binary
panic = "abort" # audit deps first!
strip = "symbols" # smaller binary, lose backtrace names
```
See [cargo-config.md](cargo-config.md) for `RUSTFLAGS` interactions with these knobs.
## `profile.dev.package` Overrides for Slow Deps
Heavy dependencies stay painful in debug mode unless overridden. Compile expensive deps in release mode once; they cache in `target/` and never recompile slowly again:
```toml
[profile.dev.package."*"]
opt-level = 0 # default: dev profile for our code
[profile.dev.package.serde_derive]
opt-level = 3 # proc-macro compiled once, reused forever
[profile.dev.package.regex]
opt-level = 3 # CPU-bound, kills test wall time in debug
```
Best targets: proc-macro deps (`serde_derive`, `tokio-macros`, `async-trait`) and CPU-bound deps (`regex`, `image`, `zstd`, `ring`). Caveat: overrides only affect code compiled inside that crate — generics monomorphized in your crate use your profile.
## Workspace Compile-Time Budgets at Scale
When a workspace crosses ~20 members and 100k LOC, build time dominates dev iteration. Strategies that compound:
- **Split feature flags** so dev disables expensive deps (typed-builder, derive-heavy serde features). See [features-conditional.md](features-conditional.md).
- **Shared target dir**: `CARGO_TARGET_DIR=/shared/target` across workspaces, or `sccache` for cross-machine caching.
- **`cargo-nextest`** for test parallelism — scales beyond `cargo test`'s per-binary model on workspaces with many crates.
- **Member partitioning**: heavy proc-macro deps live in a single leaf crate; leaves only rebuild on `cargo build -p leaf`.
- **`RUSTFLAGS="-Zthreads=8"`** on nightly enables the parallel rustc frontend, a measurable win on workspaces with many small crates.
## Cargo.toml Metadata Completeness
For any crate intended for crates.io, the `[package]` block must be filled out completely. Missing fields silently make your crate undiscoverable or ship the wrong files.
```toml
[package]
name = "mycrate"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"
description = "Concise one-line summary." # required for publish
license = "MIT OR Apache-2.0"
repository = "https://github.com/org/repo"
documentation = "https://docs.rs/mycrate" # explicit, not inferred
readme = "README.md"
keywords = ["cli", "parser"] # max 5
categories = ["command-line-utilities"] # from crates.io/category_slugs
include = ["src/**/*", "Cargo.toml", "README.md", "LICENSE-*"]
```
Missing `categories`/`keywords` and crates.io search ranks you nowhere. Missing `include` and `cargo publish` ships your `target/`, `.env`, fixture data, and any dotfile not in `.gitignore`.
## Additional Review Checks
- [Cargo.toml] PANIC_ABORT_IN_RELEASE_WITHOUT_AUDIT — `panic = "abort"` set globally; review every `catch_unwind` site and `Drop` impl that performs cleanup. The setting is global across all deps.
- [Cargo.toml] MISSING_LTO_IN_RELEASE_PROFILE — release profile without `lto = "thin"` or `"fat"` leaves cross-crate inlining on the table; add when shipping a binary or hot library.
- [Cargo.toml] CODEGEN_UNITS_NOT_TUNED_FOR_BINARY — final binary uses default `codegen-units = 16`; consider `1` plus LTO for the shipped artifact.
- [Cargo.toml] PROC_MACRO_DEP_NOT_OVERRIDDEN — heavy proc-macro dep (`serde_derive`, `tokio-macros`) without `[profile.dev.package.X] opt-level = 3`; debug builds pay the cost every clean rebuild.
- [Cargo.toml] MISSING_METADATA_FOR_PUBLICATION — package missing `description`, `license`, or `repository` for crates.io; publish will fail or the crate will be undiscoverable.
- [Cargo.toml] MISSING_INCLUDE_OR_EXCLUDE — no `include` or `exclude`; `cargo publish` ships build artifacts, dotfiles, and fixtures not in `.gitignore`.
- [Cargo.toml] STRIP_NOT_SET_IN_RELEASE — release binary keeps debug symbols; `strip = "symbols"` reduces binary size 50-80% for typical Rust artifacts.
- [Cargo.toml] EDITION_NOT_DECLARED — `edition = "..."` missing from `[package]`; silently defaults to 2015 and disables most modern idioms.
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: 321k | 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: 197k | 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 |