Rust

User preferences and memory live in ~/Clawic/data/rust/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/rust/ or ~/clawic/rust/), move it to ~/Clawic/data/rust/.

When To Use

• Writing or reviewing Rust: functions, traits, error types, async code, public crate APIs
• Fighting the compiler: moves, borrows, lifetimes, trait bounds, dyn compatibility, type inference
• Diagnosing runtime failures: panics, deadlocks, BorrowMutError, memory growth, segfaults through unsafe or FFI
• Cargo work: features, workspaces, lockfiles, MSRV, slow builds, CI-only failures, duplicated dependencies
• Targets beyond the host: cross-compilation, static musl binaries, no_std firmware, wasm
• Not for C++ (cpp) or language-agnostic concurrency theory (async-patterns) — this is Rust the language and its toolchain

Quick Reference

Depth on demand: compiler-errors.md error code → real cause → first move · ownership.md moves, borrows, interior mutability · lifetimes.md elision, variance, 'static, HRTB · traits.md coherence, generics vs dyn, associated types · pattern-matching.md match ergonomics, let else, exhaustiveness, Option/Result combinators, modeling states · errors.md Result design, ?, panics, backtraces · async.md runtimes, Send bounds, cancellation · concurrency.md threads, locks, channels, atomics · strings-and-text.md String/&str, UTF-8, formatting, Cow, paths · collections.md Vec, maps, sets, queues, iterators · performance.md profiling, allocation, build settings · observability.md tracing, spans, metrics, panic hooks · cargo.md features, workspaces, lockfiles, build times · modules-and-layout.md module tree, visibility, lib/bin/tests layout, when to split a crate · testing.md layout, doctests, property tests, Miri, fuzzing · unsafe.md UB rules, raw pointers, safety comments · ffi.md C interop in both directions · macros.md macro_rules! and proc macros · api-design.md public APIs and semver hazards · serde.md derive traps and format edge cases · embedded-no-std.md firmware and no_std · wasm.md browser and WASI targets · cross-compilation.md target triples, musl, linkers, containers.

Core Rules

1. Fix a borrow error at the lowest rung that compiles. The ladder (full version below) runs shorten → split → take → copy → clone → interior mutability → arena → unsafe. Every rung down trades a compile-time guarantee for a runtime one; reaching for Rc> against a rung-1 problem is the most common finding in Rust review.
2. Borrowed in arguments, owned in returns. A parameter typed String forces every caller to allocate or surrender ownership; &str accepts String, &String, and literals through deref coercion. Escape hatch: impl Into when the function genuinely stores the value.
3. Overflow checks are ON in debug and OFF in release by default. i32::MAX + 1 panics under cargo test and wraps silently in the shipped binary. For arithmetic on unbounded or untrusted input use checked_* (returns Option), saturating_* (clamps), or wrapping_* (documents intent) — or set overflow-checks = true in [profile.release] and measure that cost instead of assuming it.
4. Measure release builds only. Debug builds skip optimization and keep overflow and bounds instrumentation: arithmetic-heavy loops commonly run 10-50× slower, so a debug timing ranks nothing. Profile with [profile.release] debug = true — full optimization plus symbols, so the profiler can name frames.
5. One error type per boundary: enum outward, dynamic inward. A library returning anyhow::Error denies callers the ability to match on the failure; a binary with 40 enum variants pays for matching nobody does. Default: a thiserror enum in library crates, anyhow::Result with .context() in binaries (errors.md).
6. main prints errors with Debug, not Display. fn main() -> Result<(), MyError> on failure emits Error: and exits 1 — the Display message you wrote never appears. Either print it yourself and std::process::exit(1), or return an error type whose Debug renders the full report (anyhow::Error does).
7. Bind every guard to a real name. let _ = mutex.lock(); releases the lock on that same line — _ is not a binding, so the guard drops immediately; let _guard = mutex.lock()?; holds it to end of scope. Same trap with RefCell borrows and every other RAII handle.
8. Features are additive and unified across the entire graph. default-features = false in your manifest is a request, not a guarantee: if any crate in the tree enables tokio/full, the whole build gets full. Find the enabler with cargo tree -e features -i before arguing with the manifest.
9. Pin the toolchain and the lockfile wherever the build must reproduce. rust-toolchain.toml plus cargo build --locked in CI. Without --locked, CI resolves newer semver-compatible dependencies than your Cargo.lock and the difference arrives as a compile error nobody can reproduce locally.

Compiler Error Codes

The code names the subsystem that refused, which names the file to open. rustc --explain E0382 prints the canonical explanation; the column below is the first move that is usually right.

Pointer And Container Choice

Pick the weakest tool that expresses the need — every row costs something the row above does not.

Borrow Checker Escape Ladder

Ordered by cost. Take the first rung that compiles.

1. Shorten the borrow. NLL ends a borrow at its last use, not at end of scope: let n = v.len(); v.push(n); compiles where v.push(v.len()) does not.
2. Split the borrow. let Foo { a, b } = &mut foo; yields independent &mut to distinct fields; slice::split_at_mut does the same for slices. A &mut self method borrows the whole struct — that asymmetry explains most "obviously fine" rejections.
3. Take the value out. let buf = std::mem::take(&mut self.buf); hands you an owned value and leaves Default::default() behind; put it back when done. mem::replace when there is no sensible default.
4. Copy the small thing. An index, an id, a length: copying a usize costs nothing and removes the borrow entirely. Index-based access is a legitimate design, not a defeat.
5. Clone. Honest, and unobservable in setup, config, and error paths. A clone in a hot loop is a rung-1 problem in disguise; profile rather than guess which one you have.
6. Interior mutability. Cell for Copy, RefCell for the rest, Mutex across threads. You now own the invariant the compiler used to check, and violations arrive as runtime panics.
7. Handles instead of pointers. Vec plus u32 indices. This is the standard answer for graphs and trees with back-edges; Rc> is the version that gets rewritten a year later.
8. unsafe. Only with a // SAFETY: comment naming the invariant, and Miri in CI (unsafe.md).

Output Gates

Before emitting Rust code, verify:

• Every unwrap/expect outside tests is justified in a comment, or replaced by ?
• Public parameters take &str, &[T], or impl AsRef wherever the function only reads them
• Errors follow rule 5: enum at library boundaries, #[from] conversions, no Box in a published signature
• No std guard, Rc, or blocking call is alive across an .await
• Arithmetic on untrusted or unbounded values uses checked_* or saturating_*, never debug-only overflow checks
• Public enums and structs that may grow carry #[non_exhaustive] (api-design.md)
• Each new unsafe block carries a // SAFETY: comment naming the invariant it upholds
• The code passes cargo clippy -- -D warnings, not merely cargo build

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/rust/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: cargo test vs cargo nextest, criterion vs a custom harness, cargo vs just/make wrappers, linker choice (lld, mold) — affects the commands in testing.md and performance.md
• Conventions: module layout (mod.rs vs name.rs), builder vs plain constructors, re-export policy at the crate root, doc-comment strictness — affects modules-and-layout.md and api-design.md
• Platform: default target triple, libc flavor (gnu vs musl), hosted vs no_std, wasm target — affects cross-compilation.md, embedded-no-std.md, wasm.md
• Dependencies: appetite for adding a crate vs writing it, vetted-crate list, license and audit regime (cargo deny, cargo audit) — affects every "add a crate" recommendation
• Registries and sources: crates.io vs a private or mirrored registry, cargo vendor plus source replacement, air-gapped or offline builds, git vs path dependencies for internal crates — affects the manifest, .cargo/config.toml, and every install command in cargo.md
• Work order and gates: cargo check in the edit loop vs full builds, whether clippy runs pre-commit or only in CI, whether cargo semver-checks gates release PRs, test-before-fix discipline — affects the command sequences in performance.md, testing.md, and api-design.md
• Output format: depth of explanation vs a direct fix (see explanation_depth), whole file vs diff, comment density in emitted code, whether to show the rejected alternatives — affects the shape of every answer
• Safety posture: how proactively to surface panic, overflow, and unwrap risks vs answering only what was asked — affects Output Gates verbosity
• Cadence: dependency update and audit frequency, MSRV bump policy — affects the maintenance advice in cargo.md

Traps

Where Experts Disagree

• anyhow in libraries. Purists never allow it: callers cannot match on the failure. Pragmatists accept it in application-adjacent crates nobody programs against. The boundary both sides accept: if any consumer must branch on the failure kind, the enum is not optional.
• Clone-first vs lifetime-first. One camp writes owned data everywhere and optimizes later; the other treats every clone as debt. The line the evidence supports: clones in setup, config, and error paths are noise, clones inside hot loops are the first thing a profiler finds — so the disagreement only bites where you have measured.
• unsafe avoidance. #![forbid(unsafe_code)] teams vs teams accepting reviewed unsafe for measured wins. Neither side accepts unsafe without a SAFETY comment and Miri coverage — that is not a tradeoff, it is a defect.
• Generics vs dyn. Monomorphization is faster per call, slower to compile, and multiplies code size per instantiated type; dyn costs an indirect call and keeps one copy. Default to generics in leaf code and dyn at plugin-shaped boundaries, or wherever compile time or binary size is the measured constraint (performance.md).

Related Skills

More Clawic skills, get them at https://clawic.com/skills/rust (install if the user confirms):

• cpp — when the other side of the FFI boundary is C++, or when comparing ownership models
• go — the other systems language on the same team; different concurrency tradeoffs
• async-patterns — language-agnostic concurrency and cancellation theory behind async.md
• error-handling — cross-language error design behind rule 5

Feedback

• If useful, star it: https://clawic.com/skills/rust
• Latest version: https://clawic.com/skills/rust

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/rust.