Skip to content

Project structure: workspaces, shared manifest tables, toolchain, and xtask

Targets rust-1.99 edition-2024Last reviewed 2026-10-19Sources burntsushi corrode matklad nnethercote rust-blog rust-docs

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 with members = ["crates/*"], and name each directory after its crate. Crates you publish go under libs/, which adds "libs/*" to members.
  • 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 new inside the workspace writes the inheritance for you.
  • Pin the toolchain in rust-toolchain.toml to the targeted minor release, and set rust-version from it for an application, or from a written support policy for a library.
  • Write project automation as an xtask crate, run through a .cargo/config.toml alias, 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 the members field, e.g. members = ["crates/*"]. This minimizes churn in maintaining the members list" (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 with src/" (Alex Kladov: Large Rust Workspaces, 2021-08-22). matklad.

matklad adds four rules that the Cargo Book doesn't state:

  1. "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."
  2. 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.
  3. Keep src/lib.rs in a single-file crate: "even if crate is single file now, it might get expanded later."
  4. Put crates you publish under a separate top-level libs/, so you're "very deliberate" about which crates make a SemVer promise, and libs/ can't depend on crates/. The glob then needs both directories, as members = ["crates/*", "libs/*"], or Cargo refuses to build a libs/ 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 no package.edition to imply it. opinions/rust.md already 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 to runtime-performance.md.
  • One Cargo.lock and one target/, 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 --timings shows serialising the build. The Rust Performance Book points to --timings for 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 serde derives and other heavy procedural macros in leaf crates, or behind an optional feature in shared ones. Both matklad and corrode give this rule in the posts above.
  • Make every binary count. Each binary, example, and file in tests/ links separately. matklad merges integration tests into one tests/it/main.rs (Alex Kladov: Delete Cargo Integration Tests, 2021-02-27), and corrode agrees. That rule belongs to testing.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, and version to the member, because they differ per crate.
  • Set publish = false at the root, and override it with publish = true only in a crate under libs/. matklad gives internal crates version = "0.0.0" instead (Large Rust Workspaces), and the post never mentions publish. publish = false makes 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, as foo = { 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 = true beside a [lints.clippy] table: "cannot override workspace.lints in lints, either remove the overrides or lints.workspace = true and manually specify the lints" (editor's probe, 2026-10-19). Silence a lint where it fires with #[expect(…, reason = "…")], as opinions/rust.md already says.
  • Give a lint group priority = -1 when you turn on a group and then change one of its lints, as in pedantic = { 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 and ci.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:

[toolchain]
channel = "1.99"
components = ["clippy", "rustfmt"]
profile = "minimal"

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_error arrived in 1.87 and manual_is_multiple_of in 1.90 (from the release announcements on rust-blog, as opinions/rust.md lists them). On a floating stable, 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.99 rather than 1.99.1 takes point releases without an edit. A point release contains fixes only. 1.99.1 fixed wcslen, FFI bool returns on x86-64, and rust-lld on 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:

[alias]
xtask = "run --package xtask --"

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 xtask a workspace member, so it shares the lockfile and the alias works from any directory. A separate --manifest-path workspace is allowed but discouraged.
  • Keep its compile time low: few dependencies, and no heavy procedural macros.
  • Run Cargo through the CARGO environment 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 include missing_lints_inheritance, unused_workspace_dependencies, and unused_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-versions added the lints to opinions/rust.md on 2026-11-15, and resolve-research should 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), which agents/checks.md already tracks as a possible replacement for xtask subcommands.

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-research to create opinions/project-structure.md. Its first sentence is the opening list here. It needs these sections: workspace layout, the three shared tables, the toolchain file and rust-version, xtask, and Cargo.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, and rust-version, license, repository, and publish = false in [workspace.package]. Add an empty [workspace.dependencies] with a comment on declaring versions only.
    • templates/rust-toolchain.toml and templates/.cargo/config.toml, which PLAN.md plans: channel = "1.99" with clippy and rustfmt, and the xtask alias. This settles the deferred decision PLAN.md records for refresh-rust-versions: the templates pin the minor release.
  • The planned justfile template has no citable source. resolve-research should either drop it from the template set, reduce it to recipes that only call cargo and cargo xtask, or record it as a house opinion through weave-house-opinion.
  • Hand off what other topics own: integration-test layout and doctests to testing.md, [profile.release] to runtime-performance.md, MSRV checks in CI and build.warnings = "deny" to ci.md, and which lints to set to rust.md and ci.md.
  • Rust 1.100, released 2026-11-12, stabilised Cargo's lints. refresh-rust-versions added missing_lints_inheritance and three more to opinions/rust.md on 2026-11-15.
  • No vet-source candidate. The roster supported every recommendation. The Microsoft guidelines agree throughout, but they're already on the watch list until 2027-08-11.