Skip to content

existential-birds/beagle / plugins/beagle-rust/skills/rust-project-setup

rust-project-setup

Verified

Guidance 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.

FileKindSize
SKILL.mdskill md6.4 KB
references/cargo-config.mdmarkdown10.3 KB
references/ci-setup.mdmarkdown6.0 KB
references/features-conditional.mdmarkdown11.6 KB
references/no-std.mdmarkdown5.6 KB
references/workspace-layout.mdmarkdown10.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.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 321kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall