diff options
Diffstat (limited to 'docs/bootstrap-fresh.md')
| -rw-r--r-- | docs/bootstrap-fresh.md | 46 |
1 files changed, 38 insertions, 8 deletions
diff --git a/docs/bootstrap-fresh.md b/docs/bootstrap-fresh.md index b0dd3f8..b3c9112 100644 --- a/docs/bootstrap-fresh.md +++ b/docs/bootstrap-fresh.md @@ -10,6 +10,7 @@ Install the `rust-starter` lint posture cleanly: - root `Cargo.toml` owns lint levels - every crate inherits workspace lint policy - `rust-toolchain.toml` is pinned exactly +- project-local `.cargo/config.toml` routes Cargo output to `/data/main/cargo-target/<project-slug>` - `clippy.toml` stays tiny and only carries structured config - the runner stays thin and reads canonicalization and verification command vectors plus the source-file cap from workspace metadata instead of restating policy @@ -22,10 +23,11 @@ Before copying the template, decide: - license policy - exact pinned stable toolchain - actual MSRV / `rust-version` +- Cargo target-dir slug under `/data/main/cargo-target`, normally the target repo directory name - whether tests should allow `expect`, `unwrap`, or `panic` - whether the repo is library-heavy enough to keep rustdoc linting in the fast gate or only the deep gate - whether unsafe Rust is forbidden or tightly-governed -- whether the default `2500`-line source-file cap should stay as-is or be tightened for this repo +- whether the default `3000`-line source-file cap should stay as-is or be tightened for this repo - how to merge the Rust style doctrine link into any existing target `AGENTS.md` guidance ## Files To Start From @@ -34,6 +36,7 @@ Use these as the concrete baseline: - [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md) - [template/fresh/AGENTS.md](/home/main/programming/projects/rust_starter/template/fresh/AGENTS.md) +- [template/fresh/.cargo/config.toml](/home/main/programming/projects/rust_starter/template/fresh/.cargo/config.toml) - [template/fresh/Cargo.toml](/home/main/programming/projects/rust_starter/template/fresh/Cargo.toml) - [template/fresh/rust-toolchain.toml](/home/main/programming/projects/rust_starter/template/fresh/rust-toolchain.toml) - [template/fresh/clippy.toml](/home/main/programming/projects/rust_starter/template/fresh/clippy.toml) @@ -41,7 +44,7 @@ Use these as the concrete baseline: - [template/fresh/crates/app/Cargo.toml](/home/main/programming/projects/rust_starter/template/fresh/crates/app/Cargo.toml) - [template/fresh/crates/app/src/main.rs](/home/main/programming/projects/rust_starter/template/fresh/crates/app/src/main.rs) -Do not copy them mechanically. Replace the placeholder members, names, license, and version/toolchain values. +Do not copy them mechanically. Replace the placeholder members, names, license, Cargo target-dir slug, and version/toolchain values. ## Sequence @@ -69,13 +72,35 @@ Keep the command vectors in `[workspace.metadata.rust-starter]` even if you late The fresh template exports an ordered `canonicalize_commands` pipeline. Keep it repo-owned in the root manifest and make the default `check` path run it automatically before the verification gate so humans and agents do not need to remember a separate pre-pass. -Also keep the source-file cap in `[workspace.metadata.rust-starter.source_files]`. The starter default is a hard `2500`-line limit across `*.rs` files. Tighten it if the repo already has sharper discipline. +Also keep the source-file cap in `[workspace.metadata.rust-starter.source_files]`. The starter default is a hard `3000`-line limit across `*.rs` files. Tighten it if the repo already has sharper discipline. -### 3. Pin the toolchain +### 3. Install project-local Cargo target config + +Create or adapt the target repo's `.cargo/config.toml` before running Cargo commands: + +```toml +[build] +target-dir = "/data/main/cargo-target/<project-slug>" +``` + +Use the target repo directory name as the default slug. If two repos share a +directory basename, append a short path hash or another stable disambiguator. +The point is a clean, checked-in per-repo target directory under the global +Cargo target volume, not a source-tree `target/` directory and not command-line +`--target-dir` folklore. + +This is a repo-local ratchet. Do not mutate user-global Cargo config during +bootstrap; if a repo has not opted in yet, the developer's global Cargo config +remains the fallback. + +If `.cargo/config.toml` already exists, merge the `[build] target-dir` value +without overwriting unrelated Cargo configuration. + +### 4. Pin the toolchain Write `rust-toolchain.toml` early, before deciding whether a lint is noisy or broken. Lint output is part of the toolchain contract. -### 4. Make every crate inherit lint policy +### 5. Make every crate inherit lint policy Each member crate must contain: @@ -86,13 +111,13 @@ workspace = true Do not rely on memory or convention here; add it explicitly. -### 5. Add `clippy.toml` only if it carries real configuration +### 6. Add `clippy.toml` only if it carries real configuration The default template only relaxes `expect`, `unwrap`, and `panic` inside tests. If the target repo does not want that, delete the file instead of leaving inert config behind. Do not move global allow/deny policy into `clippy.toml`. -### 6. Add a thin runner +### 7. Add a thin runner The template `check.py` is intentionally small. It reads canonicalization and verification commands plus the source-file policy from workspace metadata, enforces the file cap, and then runs the Rust commands. @@ -110,7 +135,7 @@ If the target repo already prefers another orchestration surface, keep that surf If the repo has checked-in generated Rust that should not count against the cap, express that with explicit `exclude` patterns under `[workspace.metadata.rust-starter.source_files]` instead of weakening the global limit. -### 7. Keep the deep gate opt-in +### 8. Keep the deep gate opt-in The template only installs the fast gate. Add the deeper posture when the repo is mature enough: @@ -126,13 +151,17 @@ The template only installs the fast gate. Add the deeper posture when the repo i - do not enable `clippy::restriction` wholesale - do not enable `clippy::nursery` wholesale - do not duplicate lint policy in scripts, CI, and editor config +- do not pass `--target-dir` from runners, CI, or command vectors; use `.cargo/config.toml` +- do not change user-global Cargo config as part of bootstrapping a target repo - do not leave placeholder toolchain or MSRV values unreviewed ## Acceptance Checklist - root `Cargo.toml` contains `[workspace.lints.rust]`, `[workspace.lints.rustdoc]`, and `[workspace.lints.clippy]` - target `AGENTS.md` links to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md) +- target `.cargo/config.toml` contains `[build] target-dir = "/data/main/cargo-target/<project-slug>"` - root `Cargo.toml` owns warning-fatality policy, e.g. `warnings = "deny"` under `[workspace.lints.rust]`, rather than hiding it in runner flags +- root `Cargo.toml` preserves the global wildcard/glob carve-outs; compact `*` imports are intentionally allowed for token economy - root `Cargo.toml` contains canonical command vectors in `[workspace.metadata.rust-starter]` - root `Cargo.toml` contains an ordered `canonicalize_commands` pipeline in `[workspace.metadata.rust-starter]` - root `Cargo.toml` contains `[workspace.metadata.rust-starter.source_files]` with an intentional `max_lines` value @@ -141,5 +170,6 @@ The template only installs the fast gate. Add the deeper posture when the repo i - `clippy.toml` is either tiny and justified or absent - the default `check` path canonicalizes before verification, and a non-mutating `verify` path exists for CI or drift detection - no runner or CI file duplicates the Clippy allowlist +- no runner, CI file, or manifest-owned command vector passes `--target-dir` Read [docs/rust-linting-proposal.md](/home/main/programming/projects/rust_starter/docs/rust-linting-proposal.md) only when you need rationale or policy nuance. |