Project structure: workspaces, shared manifest tables, toolchain, and xtask
Unresolved research. This topic is evidence that research-topic gathered, waiting on resolve-research. It isn't an opinion, and it can cite unvetted material. Follow the opinions instead.
Structure every multi-crate repository as one Cargo workspace whose root is a virtual manifest, and declare every shared setting once at the root:
- Put the crates one level deep under
crates/, list them withmembers = ["crates/*"], and name each directory after its crate. Crates you publish go underlibs/, which adds"libs/*"tomembers. - Declare shared package fields in
[workspace.package], every external dependency's version in[workspace.dependencies], and the lint levels in[workspace.lints]. Each member inherits all three.cargo newinside the workspace writes the inheritance for you. - Pin the toolchain in
rust-toolchain.tomlto the targeted minor release, and setrust-versionfrom it for an application, or from a written support policy for a library. - Write project automation as an
xtaskcrate, run through a.cargo/config.tomlalias, instead of shell scripts. - Commit
Cargo.lock, for libraries too.
Everything here is stable in Rust 1.99.1 (released 2026-10-15). Cargo's own lints, which catch a member that forgets to inherit [workspace.lints], were unstable on nightly as of 2026-10-19, so they're in Coming next. They're stable since Rust 1.100.0 (released 2026-11-12), and opinions/rust.md covers them.
No opinion file covers this. opinions/rust.md sets edition and resolver in its Edition 2024 section, and templates/Cargo.toml already holds [workspace], [workspace.package], and [workspace.lints.clippy]. Neither says how to lay out the crates, which fields to share, or how to pin the toolchain. This is the second topic in PLAN.md: Phase 6, whose target is opinions/project-structure.md.
Workspace layout
Make the root a virtual manifest, and keep every crate one level deep under crates/. Two citable sources agree:
- The Cargo Book: "Keep all member packages in a flat directory (commonly
crates/) and use a glob pattern for themembersfield, e.g.members = ["crates/*"]. This minimizes churn in maintaining thememberslist" (The Cargo Book: Workspaces).rust-docs. - matklad: "Make the root of the workspace a virtual manifest", and nest everything else, the main crate included, "one-level deep under
crates/". A main crate at the root "pollutes the root withsrc/" (Alex Kladov: Large Rust Workspaces, 2021-08-22).matklad.
matklad adds four rules that the Cargo Book doesn't state:
- "The name of each directory is equal to the name of the crate", and "Don't succumb to the temptation to strip common prefix from folder names."
- Keep the layout flat, not a hierarchy, because Cargo's crate namespace is flat anyway, and moving or splitting a crate needs no new folder.
- Keep
src/lib.rsin a single-file crate: "even if crate is single file now, it might get expanded later." - Put crates you publish under a separate top-level
libs/, so you're "very deliberate" about which crates make a SemVer promise, andlibs/can't depend oncrates/. The glob then needs both directories, asmembers = ["crates/*", "libs/*"], or Cargo refuses to build alibs/crate that no member depends on: "current package believes it's in a workspace when it's not" (editor's probe on Cargo 1.99.1, 2026-10-19).
He scopes the advice to projects of roughly 10 thousand to 1 million lines. Below that, a single package needs no workspace.
The watch-listed Microsoft guidelines (watch-list, ms-rust-guidelines) agree with the flat crates/ folder and with never nesting crates, but allow subfolders such as server/ and client/ past one or two dozen crates (Microsoft: Pragmatic Rust Guidelines, Project, version 2026.6). No citable source covers that size, so the opinion should keep matklad's single level.
What the root holds
A virtual manifest has no package, so a few settings can live only there (The Cargo Book: Workspaces):
resolver = "3", because there's nopackage.editionto imply it.opinions/rust.mdalready says this.[profile.*],[patch], and[replace]. Cargo ignores them in a member's manifest. The Rust Performance Book makes the same point for profiles (The Rust Performance Book: Build Configuration).nnethercote. The profile settings themselves belong toruntime-performance.md.- One
Cargo.lockand onetarget/, shared by every member.
default-members lists the members that a bare cargo build at the root acts on. In a virtual workspace, it defaults to every member, which is what the opinion wants.
Shape the crate graph for build time
Keep the crate graph wide, not a chain: a shared vocabulary crate, independent feature crates, and one leaf that ties them together. Cargo then compiles the feature crates in parallel (Alex Kladov: Fast Rust Builds, 2021-09-04). matklad.
- Split a crate that
cargo build --timingsshows serialising the build. The Rust Performance Book points to--timingsfor exactly this (The Rust Performance Book: Compile Times).nnethercote. corrode recommends workspaces for the same reason, because only the crates that changed recompile (Matthias Endler: Tips For Faster Rust Compile Times, updated 2026-03-14).corrode. - Keep
serdederives and other heavy procedural macros in leaf crates, or behind an optional feature in shared ones. Bothmatkladandcorrodegive this rule in the posts above. - Make every binary count. Each binary, example, and file in
tests/links separately. matklad merges integration tests into onetests/it/main.rs(Alex Kladov: Delete Cargo Integration Tests, 2021-02-27), and corrode agrees. That rule belongs totesting.md.
Document the structure
Add an ARCHITECTURE.md beside the README once a project passes about 10 thousand lines: a bird's-eye view, then a code map that answers "where's the thing that does X?", then the invariants and boundaries (Alex Kladov: ARCHITECTURE.md, 2021-02-06). matklad. The post isn't specific to Rust, but its example is the architecture document of rust-analyzer.
Shared manifest tables
Declare every setting that two members share once at the root, and inherit it. Workspace inheritance has been stable since Rust 1.64 (Rust Blog: Announcing Rust 1.64.0), and [workspace.lints] since 1.74 (Rust Blog: Announcing Rust 1.74.0). rust-blog.
Since Cargo 1.75, cargo new inside a workspace adds the new crate to members (The Cargo Book: Changelog, Cargo 1.75). The editor's probe on 2026-10-19, with Cargo 1.99.1, showed that it also writes .workspace = true for each key in [workspace.package], and [lints] workspace = true. A member made by hand or copied from another repository gets neither.
[workspace.package]
Put edition, rust-version, license, repository, and publish in [workspace.package], and inherit each with <key>.workspace = true. The table accepts 16 keys: authors, categories, description, documentation, edition, exclude, homepage, include, keywords, license, license-file, publish, readme, repository, rust-version, and version (The Cargo Book: Workspaces). rust-docs.
- Leave
name,description, andversionto the member, because they differ per crate. - Set
publish = falseat the root, and override it withpublish = trueonly in a crate underlibs/. matklad gives internal cratesversion = "0.0.0"instead (Large Rust Workspaces), and the post never mentionspublish.publish = falsemakes Cargo refuse to publish, which is the stronger guard (The Cargo Book: The manifest format), so recommend both.
[workspace.dependencies]
Declare each external dependency's version once, in [workspace.dependencies], and inherit it in each member with dep.workspace = true. A member may add only three keys beside workspace: optional, features, and default-features. Its features add to the workspace entry's (The Cargo Book: Inheriting a dependency from a workspace). rust-docs.
New in 1.99: in an edition 2024 member, default-features overrides the workspace entry's value. Before 1.99, or in an earlier edition, default-features = false in a member "may be ignored or rejected" unless the workspace entry also sets it. The editor's probe confirmed both behaviours on Cargo 1.99.1. A member on edition 2024 that turned off a path dependency's default features built without them, and the same member on edition 2021 built with them.
So, on the targeted toolchain:
- Declare only the version in
[workspace.dependencies], with no features, and let each member ask for the features it uses. Feature unification still builds the union of every member's features into one copy (The Cargo Book: Feature unification), so a feature in the workspace entry turns on everywhere. The watch-listed Microsoft guidelines say the same (watch-list,ms-rust-guidelines). - Put path dependencies between members in
[workspace.dependencies]too, asfoo = { path = "crates/foo" }. Members then name each other the same way they name an external crate. The Cargo Book's own example inherits a path dependency this way.
# Root Cargo.toml
[workspace.dependencies]
serde = "1.0.228"
foo = { path = "crates/foo" }
# crates/bar/Cargo.toml
[dependencies]
serde = { workspace = true, features = ["derive"] }
foo.workspace = true
This is a fragment: the root needs its [workspace] table, and the member its [package].
[workspace.lints]
Set every lint level in [workspace.lints], and put [lints] workspace = true in every member. Inheritance is opt-in, and Cargo's own documentation warns that "many people mistakenly think that workspace.lints is implicitly inherited when it is not" (The Cargo Book: Lints). rust-docs.
- A member can't override one inherited lint. Cargo 1.99.1 rejects
[lints] workspace = truebeside a[lints.clippy]table: "cannot overrideworkspace.lintsinlints, either remove the overrides orlints.workspace = trueand manually specify the lints" (editor's probe, 2026-10-19). Silence a lint where it fires with#[expect(…, reason = "…")], asopinions/rust.mdalready says. - Give a lint group
priority = -1when you turn on a group and then change one of its lints, as inpedantic = { level = "warn", priority = -1 }. A lower priority is applied first, so the single lint wins (The Cargo Book: The[lints]section).rust-docs. - Which lints to set is
rust.md's andci.md's business. This opinion owns only where they're declared.
[lints] in a virtual manifest has been an error since Cargo 1.76, because the author almost certainly meant [workspace.lints] (The Cargo Book: Changelog, Cargo 1.76). rust-docs.
Toolchain and rust-version
rust-toolchain.toml
Commit a rust-toolchain.toml that pins the targeted minor release, with Clippy and rustfmt:
The file's format and precedence are rustup's: channel takes stable, a version such as 1.99 or 1.99.1, or a dated nightly, and only cargo +<toolchain>, RUSTUP_TOOLCHAIN, and a directory override beat it (The rustup book: Overrides). The rustup book is a tool's own documentation, so it's a reference for the format, not a source for the recommendation.
Why pin, and not channel = "stable":
- A new stable release adds warn-by-default lints, and CI denies warnings. For example,
io_other_errorarrived in 1.87 andmanual_is_multiple_ofin 1.90 (from the release announcements onrust-blog, asopinions/rust.mdlists them). On a floatingstable, a release day breaks the build of a commit that passed the day before. - corrode pins the compiler version in build images, and uses the same one in every stage (Matthias Endler: Hardening Rust Code For Production, 2026-07-23).
corrode. The same post builds with--locked. - Pinning
1.99rather than1.99.1takes point releases without an edit. A point release contains fixes only. 1.99.1 fixedwcslen, FFIboolreturns on x86-64, andrust-lldon macOS (Rust Blog: Announcing Rust 1.99.1).rust-blog.
The argument against pinning: corrode also advises readers to "stick to the stable release of Rust if at all possible" and to run rustup update regularly (Matthias Endler: Long-term Rust Project Maintenance, 2024-05-13), and its CI examples use the latest stable. That's an argument against nightly and against falling behind, not against pinning a stable release. A pin that a bot bumps on each release keeps both. Renovate, which this repository already runs, can bump rust-toolchain.toml, and the repository's own refresh-rust-versions skill does the same for its templates. No roster source argues for a floating stable in a toolchain file. Unvetted discussion, such as forum threads and CI templates, splits between the two, so this recommendation rests on the lint argument.
rust-version
Set rust-version in [workspace.package], and inherit it in every member. Cargo refuses to build a package on an older toolchain, cargo add picks the newest dependency version that supports it, and edition 2024's resolver 3 prefers dependency versions that do (The Cargo Book: Rust version, Resolver: Rust version). Clippy reads it as its msrv, so it never suggests a newer API (Clippy: Lint configuration). The resolver has been MSRV-aware since 1.84 (Rust Blog: Announcing Rust 1.84.0). rust-docs and rust-blog.
The value depends on what the workspace ships:
| Workspace ships | rust-version |
Why |
|---|---|---|
| An application or service | The pinned toolchain's minor release, as "1.99" |
Nobody else compiles it, so the toolchain file and rust-version say the same thing |
| A published library | The oldest release the written support policy keeps | Users compile it on their own toolchain, so it's a promise, and the Cargo Book asks for a policy |
For a library, the Cargo Book says to "choose a policy for what Rust versions to support and when that is changed", treats raising rust-version as "a minor incompatibility", and gives three example policies: the last N releases, every even release, or a calendar window (The Cargo Book: Rust version). rust-docs. It doesn't pick one.
burntsushi's crates write a policy down. regex "can be increased in minor version updates", and patch releases keep it (regex: README). Jiff "will never use a Rust version that requires a Rust compiler released in the previous 1 year", and raises it only in a minor release (Jiff: README). burntsushi, writing in repository documentation under the dormancy exception. Tokio's six-month rolling window (unvetted, from its docs.rs page) and the Microsoft guidelines' "a few versions behind" (watch-list) are shorter.
Recommend Jiff's form for a published library: support every stable release from the last 12 months, raise rust-version only in a minor release, and say so in the README. It's the only written policy from a citable source, and a calendar window is one of the Cargo Book's three examples. Checking it in CI, with cargo-hack or cargo-msrv as the Cargo Book suggests, belongs to ci.md.
This doesn't conflict with the repository's "never downgrade" rule. targets: names the toolchain the opinions and templates are written for. A library's rust-version is a promise to its users, and review-project already reads it that way.
xtask
Write the project's automation in Rust, as a binary crate named xtask inside the workspace, and alias it in .cargo/config.toml:
cargo xtask <task> then works from any directory in the workspace, needs only Cargo and rustc, and runs the same on every platform (matklad/cargo-xtask: README). matklad. "To avoid both the bloat and proliferation of ad-hoc workflows, write all automation in Rust in a dedicated crate" (Large Rust Workspaces). The README adds three rules:
- Make
xtaska workspace member, so it shares the lockfile and the alias works from any directory. A separate--manifest-pathworkspace is allowed but discouraged. - Keep its compile time low: few dependencies, and no heavy procedural macros.
- Run Cargo through the
CARGOenvironment variable, so a nested build uses the same toolchain.
Give the crate publish = false. The alias form follows the Cargo Book's [alias] table (The Cargo Book: Configuration, [alias]), which allows a string or an array, but can't redefine a built-in command.
matklad's later "Basic Things" generalises the rule: "a single, clearly documented command for building and testing the project", with glue code in the project's main language, not shell or Python (Alex Kladov: Basic Things, 2024-03-22). matklad.
just and cargo-make have no citable source. No roster source compares them with xtask. This repository itself puts a justfile in front of cargo xtask, and PLAN.md lists a justfile among the planned templates. That's at odds with matklad's single-language rule unless the justfile holds only one-line recipes that call cargo. See What this means for the repository.
Cargo.lock
Commit Cargo.lock in every workspace, libraries included. The Rust project changed its guidance on 2023-08-29: cargo new no longer ignores the lockfile for a library, and the starting point is to commit it, because a lockfile makes git bisect and CI deterministic (Rust Blog: Change in Guidance on Committing Lockfiles). rust-blog. The Cargo FAQ keeps one caveat: the lockfile "does not affect the consumers of your package", so test against the latest dependencies as well (The Cargo Book: FAQ). rust-docs. That CI job belongs to ci.md.
Coming next
These are unstable on nightly as of 2026-10-19, so they're not yet an opinion:
- Cargo's own lints and
[lints.cargo](The Cargo Book: Lints, "can only be used on nightly toolchains"). They includemissing_lints_inheritance,unused_workspace_dependencies, andunused_workspace_package_fields, each warn by default, which Cargo 1.95 added on nightly. They'd catch a member that forgets[lints] workspace = true. Stable since 1.100.0, released 2026-11-12 (Rust Blog: Announcing Rust 1.100.0), so this row and its quote are out of date.refresh-rust-versionsadded the lints toopinions/rust.mdon 2026-11-15, andresolve-researchshould link there instead of restating them. - Per-package feature unification (
-Zfeature-unification, rust-lang/cargo#14774), which would replace a workspace-hack crate. - Public and private dependencies (
-Zpublic-dependency, rust-lang/rust#44663). - Path bases (
-Zpath-bases, rust-lang/cargo#14355). - Single-file packages (
-Zscript, rust-lang/cargo#12207), whichagents/checks.mdalready tracks as a possible replacement forxtasksubcommands.
niko-matsakis proposes "battery packs", crates that bundle recommended dependencies, features, and templates, with a cargo-bp prototype (Niko Matsakis: Battery packs, 2026-07-15). It's a proposal and changes nothing in Cargo, so it isn't cited in the frontmatter, and it belongs in no opinion yet.
What this means for the repository
- No opinion covers the topic. Run
resolve-researchto createopinions/project-structure.md. Its first sentence is the opening list here. It needs these sections: workspace layout, the three shared tables, the toolchain file andrust-version,xtask, andCargo.lock. List it under README.md's Scope and in the layout tree. - The templates need these changes:
templates/Cargo.toml:members = ["crates/*"]with a comment to add"libs/*"for published crates, andrust-version,license,repository, andpublish = falsein[workspace.package]. Add an empty[workspace.dependencies]with a comment on declaring versions only.templates/rust-toolchain.tomlandtemplates/.cargo/config.toml, which PLAN.md plans:channel = "1.99"withclippyandrustfmt, and thextaskalias. This settles the deferred decision PLAN.md records forrefresh-rust-versions: the templates pin the minor release.
- The planned
justfiletemplate has no citable source.resolve-researchshould either drop it from the template set, reduce it to recipes that only callcargoandcargo xtask, or record it as a house opinion throughweave-house-opinion. - Hand off what other topics own: integration-test layout and doctests to
testing.md,[profile.release]toruntime-performance.md, MSRV checks in CI andbuild.warnings = "deny"toci.md, and which lints to set torust.mdandci.md. - Rust 1.100, released 2026-11-12, stabilised Cargo's lints.
refresh-rust-versionsaddedmissing_lints_inheritanceand three more toopinions/rust.mdon 2026-11-15. - No
vet-sourcecandidate. The roster supported every recommendation. The Microsoft guidelines agree throughout, but they're already on the watch list until 2027-08-11.