skip to content

In Cargo, what does a workspace holding api, core and cli crates share across its members that three standalone packages would each keep separately?

level: juniorimportance: should knowfreq 48%

answer

  1. one file at the root
  2. one output directory
  3. commands across all members
  4. root-only manifest sections

basics

~20 s

A Cargo workspace gives its member packages one Cargo.lock and one target directory at the workspace root, lets one command build or test every member, and reads profiles and [patch] only from the root manifest.

solid answer

~30 s

A workspace is a set of packages managed together. All members share **one `Cargo.lock`** at the workspace root, so every member resolves a dependency to the same locked version, and **one `target/` directory**, so a dependency is built once and reused across members that request it with the same features and profile. Commands can span members (`cargo test --workspace`) or pick one (`-p ledger-api`). `[profile.*]`, `[patch]` and `[replace]` are honoured only in the root `Cargo.toml`. What stays per member: each package keeps its own `Cargo.toml`, name, dependency list and targets, and is published separately.

code

toml · 14 lines
toml
# Cargo.toml at the repository root
[workspace]
members = ["crates/*"]
resolver = "3"

# crates/cli/Cargo.toml
[package]
name = "ledger-cli"
version = "0.4.0"
edition = "2024"

[dependencies]
ledger-api = { path = "../api" }
ledger-core = { path = "../core" }

go deeper

for a junior

Recall the two shared artefacts: one Cargo.lock and one target directory at the workspace root, plus commands that run across members.

for a middle

Explain that members are still separate packages with their own manifests, and that only the root manifest's profiles and patches are honoured.

for a senior

Show why one resolution matters in production: members pass types from a shared dependency only because the single lockfile locks one version.

for a principal

Frame the workspace as the unit that fixes one tested dependency set and one release profile for a whole repository, and say when a crate belongs outside it.

## What a workspace is A **Cargo workspace** is a collection of one or more **packages** (each with its own `Cargo.toml`) that Cargo manages together. The workspace is declared by a `[workspace]` table in a top-level `Cargo.toml`; the directory holding that file is the **workspace root**. A repository with three crates (an `api` library, a `core` library and a `cli` binary) is the textbook case: they change together, depend on each other through path dependencies, and are tested together in CI. Without a workspace, each of the three directories is a standalone package. Each gets its own lockfile, its own `target/` directory and its own copy of every compiled dependency, and nothing forces the three to agree on which version of a shared dependency they use. ## What the members share - **One `Cargo.lock`.** It lives at the workspace root; members never get their own. Running `cargo build` inside `crates/core` still reads and writes the root lockfile. Because there is a single resolution, a crate that two members both depend on through compatible requirements is locked once, so `ledger-core` and `ledger-api` see the same `serde` and pass its types between them without a version mismatch. - **One output directory.** By default the shared build directory is `target/` in the workspace root. A dependency compiled for one member is reused by the others, as long as they request it with the same features and profile. - **Commands that span members.** `cargo build --workspace`, `cargo test --workspace` and `cargo check --workspace` act on every member; `-p NAME` selects one, and `--exclude NAME` (together with `--workspace`) drops one. - **Root-only settings.** The `[profile.*]`, `[patch]` and `[replace]` sections are recognised only in the root manifest; in a member's `Cargo.toml` Cargo ignores them and prints a warning. - **Optional inheritance.** A root can declare `[workspace.package]` and `[workspace.dependencies]` so members inherit a version, an edition or a dependency requirement by writing `key.workspace = true`. Inheritance is opt-in, key by key. ## What stays per member | Concern | Shared at the root | Kept by each member | |---|---|---| | `Cargo.lock` | yes | never its own | | `target/` directory | yes, by default | none | | `[profile.*]`, `[patch]` | yes, root only | ignored with a warning | | Name, targets, `[dependencies]` | no | its own `Cargo.toml` | | Version, edition | only if inherited | otherwise its own | | Publishing | no | each package separately | Each member is still a separate package that compiles to its own crate or crates. A member does not see another member's code unless it declares a dependency on it, usually a path dependency such as `ledger-core = { path = "../core" }`. ## Where commands look 1. Cargo finds the workspace by walking up from the current directory to the first `Cargo.toml` that has a `[workspace]` table. 2. Run inside a member directory, a bare `cargo build` builds only that member and what it depends on; the output still lands in the root `target/`. 3. Run at the workspace root, it builds the `default-members` list if one is set; otherwise the root package (if the root manifest has a `[package]`) or, for a root without one, every member. ```console $ cd crates/core $ cargo build Compiling ledger-core v0.1.0 (.../crates/core) Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.03s $ ls Cargo.toml src $ ls ../.. Cargo.lock Cargo.toml crates target ``` ## Why teams use one - **Consistency:** one lockfile means one tested set of dependency versions for the whole repository. - **Build time and disk:** shared `target/` avoids compiling the same dependencies three times. - **One-command CI:** `cargo test --workspace` runs every member's tests in one invocation. - **Central settings:** one release profile and one set of patches for all members. The workspace does not merge the crates. `ledger-cli` still compiles as its own crate, keeps its own dependency list, and could be published on its own. The workspace changes what is shared around the crates, not what is inside them. How a monorepo should coordinate versions in general is a broader subject; this answer is about what Cargo itself shares.

  • If ledger-core asks for serde "1.0.200" and ledger-api asks for serde "1.0.150", how many serde versions does the workspace build?
    One. Both requirements are caret requirements in the same compatible 1.x range, and the workspace has a single `Cargo.lock`, so Cargo locks one `serde` version that satisfies both (the newest available that meets `>=1.0.200`). Both members compile against that one `serde`, so a type from it can cross the member boundary. How Cargo picks that version is a resolver question; the workspace only guarantees there is one lockfile.
  • Can you still build or test a single member on its own inside a workspace?
    Yes. Run the command inside the member's directory, or anywhere in the workspace with `-p NAME`, for example `cargo test -p ledger-core`. Cargo builds that package and its dependencies only, using the shared lockfile and the shared root `target/`, so the result is the same versions the full workspace build uses.

  • Each member keeps its own Cargo.lock beside its Cargo.toml.
  • A workspace merges all members into one crate.
  • Members see each other's code without declaring a dependency.
  • A member's [profile.release] applies to that member's build.
  • Building inside a member puts output in that member's own target/.