Rust Impl Workspaces

rust-impl-workspaces

A Cargo workspace is one or more packages (the members) that share a single Cargo.lock, a single target/ directory, and a single root manifest. For any project larger than one crate (binary + reusable library, a CLI plus its core, a monorepo of microservices, a plugin host plus plugins), workspaces are the only correct organisational unit. Without them you get duplicate target/ directories, drifting dependency versions, duplicated metadata, and lockfile divergence across crates.

Cross-references: [[rust-impl-cargo-project]] (single-crate Cargo.toml basics, profiles, features), [[rust-core-language-versions]] (resolver 3 ships with Rust 1.84; edition 2024 defaults to it), [[rust-core-toolchain]] (rust-toolchain.toml and rustup channels for the whole workspace).

When to use this skill

• The user has, or is about to have, more than one crate in the same repository.
• A binary depends on a library that lives in the same repo.
• The user asks "how do I share serde = "1" across all my crates without copy-pasting the version".
• The user wants to set edition = "2024" once and not in every member.
• The user is choosing between resolver = "2" and resolver = "3".
• The user hits "two different versions of serde in one build" (lockfile drift between standalone Cargo projects in the same repo, fixed by promoting them to a workspace).
• The user sees target/ appearing in three different crate directories.

Quick reference

The virtual-workspace template (the default you want)

# Cargo.toml (workspace root)
[workspace]
resolver = "3"
members  = ["crates/*"]
exclude  = ["crates/scratch"]
default-members = ["crates/app"]

[workspace.package]
edition      = "2024"
rust-version = "1.85"
license      = "MIT OR Apache-2.0"
authors      = ["OpenAEC Foundation"]
repository   = "https://github.com/example/repo"

[workspace.dependencies]
serde      = { version = "1", features = ["derive"] }
tokio      = { version = "1", features = ["rt-multi-thread", "macros"] }
anyhow     = "1"
thiserror  = "2"

[workspace.lints.rust]
unsafe_code = "forbid"

[workspace.lints.clippy]
unwrap_used = "warn"

ALWAYS prefer a virtual workspace for any repo with more than one crate. The root Cargo.toml has no [package] section, so no code lives at the root; every crate is a member under crates/.

NEVER mix [workspace] and [package] at the root unless the project genuinely is "one main crate plus a few helper crates". The virtual layout is easier to reason about, easier to add members to, and never confuses tooling about which crate the root is.

Member manifests: inherit everything you can

# crates/app/Cargo.toml
[package]
name         = "app"
version      = "0.1.0"
edition.workspace      = true
rust-version.workspace = true
license.workspace      = true
authors.workspace      = true
repository.workspace   = true

[dependencies]
serde     = { workspace = true }
tokio     = { workspace = true, features = ["fs"] }
anyhow    = { workspace = true }
my-core   = { path = "../my-core" }

[dev-dependencies]
proptest = "1"

[lints]
workspace = true

ALWAYS write field.workspace = true for every inheritable key (edition, rust-version, license, authors, repository, homepage, documentation, keywords, categories, description, publish, readme, include, exclude, version). The compiler does not warn on a missing inheritance, so drift creeps in silently.

ALWAYS reference shared deps as dep = { workspace = true }. You may add features at the call site (features = ["fs"]) but you cannot override the version: that is the point.

NEVER pin a different version in a member than the one declared in [workspace.dependencies]. Cargo errors on the conflict, but the more common mistake is to forget the workspace = true and silently get the wrong version because the dependency was declared from scratch.

NEVER set optional = true inside [workspace.dependencies]. The Cargo reference disallows this. Mark the member-level entry optional instead:

# member
[dependencies]
serde = { workspace = true, optional = true }

members, default-members, exclude

[workspace]
members         = ["crates/*", "tools/codegen"]
default-members = ["crates/app", "crates/server"]
exclude         = ["crates/scratch", "crates/legacy"]

• members accepts plain paths and glob patterns (*, ?). Any path = "../foo" dependency from a member also auto-becomes a member.
• default-members is the subset that cargo build, cargo test, cargo run operate on when invoked from the workspace root without -p or --workspace. Useful when the repo has a release-critical core (build by default) and benches / tools (only on demand).
• exclude removes a path from members even when a glob would have included it. Use it for scratch directories, vendored copies, or examples that should not block CI.

ALWAYS prefer a glob (crates/*) over an enumerated list once the count exceeds three. The list is otherwise a churn magnet.

ALWAYS document why a path is in exclude with a comment in the manifest. An unexplained exclude is the second-most-likely cause of "why doesn't cargo test --workspace build my crate".

Resolver: "2" or "3"

In edition 2024 (Rust 1.85+) cargo new writes resolver = "3" for you. The resolver MUST be set on the root manifest; member-level resolver entries are ignored. In a virtual workspace it lives in [workspace]; in a root-package workspace it lives in [package].

ALWAYS write the resolver key explicitly in virtual workspaces. There is no package.edition at the root from which Cargo could infer it, and forgetting it pins you to resolver 1 with confusing feature-unification behaviour.

ALWAYS pick "3" for new edition-2024 workspaces. The MSRV-aware behaviour is strictly better when [workspace.package].rust-version is set: Cargo selects older compatible dependency versions instead of breaking the build.

NEVER mix resolver versions across members. The root resolver controls the entire workspace; per-member resolver keys are silently ignored, which is exactly the wrong failure mode for someone trying to "opt one crate into resolver 2".

Shared target/ and one Cargo.lock

Once the workspace is in place, every cargo invocation in any subdirectory writes to the root target/. This is the headline saving: a clean clone + cargo build --workspace reuses every artifact across members. Three previously-separate crates with overlapping dependencies might have produced 3 GB of target/ directories; one workspace produces 1.2 GB.

There is exactly one Cargo.lock at the workspace root. Member crates do not have their own. This guarantees every member sees the same resolved version of every dependency. A direct consequence: a member cannot depend on serde = "1.0" while another member depends on serde = "1.1" and end up with both at build time. They share one resolved serde version.

Root-only configuration items (per the Cargo reference):

• [patch.*], [replace]
• [profile.*] (including custom profiles)
• [workspace.metadata]

Entries of these tables in member manifests are ignored, with a warning in recent Cargo. ALWAYS move them to the root.

Decision tree: workspace layout

Do you have more than one crate in this repo?
|
+-- No: skip this skill. See [[rust-impl-cargo-project]].
|
+-- Yes: is there a single dominant binary or library that *is* the project,
|        and the others are small helpers?
|   |
|   +-- Yes: root-package workspace.
|   |        Root Cargo.toml has both [package] and [workspace].
|   |        Helpers live in subdirs and are listed in members.
|   |
|   +-- No / multiple peers: VIRTUAL workspace (default).
|            Root Cargo.toml has only [workspace] (no [package]).
|            All crates under crates/, members = ["crates/*"].
|
+-- Do you share dependency versions across crates?
|   +-- Yes: declare them in [workspace.dependencies], reference via workspace = true.
|
+-- Do members share metadata (edition, license, rust-version, authors)?
|   +-- Yes: declare in [workspace.package], inherit via field.workspace = true.
|
+-- Do members share lint configuration?
|   +-- Yes: declare in [workspace.lints], inherit via [lints] workspace = true.
|
+-- Pick resolver:
    edition 2024 -> "3".
    edition 2021 only -> "2".

Common operations

ALWAYS prefer cargo --workspace for CI test commands. A bare cargo test from the root only covers default-members.

Avoid these mistakes

(Full anti-pattern list with WHY and FIX in references/anti-patterns.md.)

• Duplicating dependency versions across members instead of [workspace.dependencies] (version drift, slow upgrades).
• Forgetting to set resolver explicitly in a virtual workspace (silently pins to resolver 1).
• Setting resolver on a member manifest (ignored; behaviour does not change).
• Combining [workspace] and [package] at the root for a multi-crate project that has no obvious dominant crate (use virtual).
• Excluding members with no comment explaining why (next contributor undoes it for the wrong reason).
• Per-member dev-dependency version drift (declare common test deps in [workspace.dependencies] too).
• Forgetting [workspace.package].edition and getting edition mismatch between members.
• Placing [profile.release] in a member manifest (ignored; profile lives only at the root).
• Declaring optional = true inside [workspace.dependencies] (not allowed by Cargo).
• Listing every member by name instead of using a glob (churns the root manifest on every new crate).

Reference links

• Cargo book: Workspaces
• Cargo book: Resolver versions
• Cargo book: Manifest format
• Cargo book: Inheriting a dependency from a workspace
• Cargo book: Features
• Rust 1.85 release (edition 2024 stable)
• Rust 1.84 release (resolver 3 stable)

For deeper drill-downs see:

• references/methods.md: complete table of every [workspace.*] key, valid value range, MSRV.
• references/examples.md: full three-member workspace, root + member manifests, lint config, profile overrides.
• references/anti-patterns.md: 12 documented anti-patterns with WHY and FIX.