Skip to content

Commit 362ce33

Browse files
committed
Auto merge of #11082 - epage:workspace, r=weihanglo
docs(ref): Clarify workspace settings ### What does this PR try to resolve? In reviewing the status of #10625, I was reminded - that we are having growing pains with the workspace documentation - that `workspace.resolver` isn't documented So I re-organized the workspace docs to have a high level intro / behavior description and then to focus on being a field reference, much like `manifest.md`. I could see splitting it specifically into tutorial/reference like the overriding dependencies document does it. When adding `workspace.resolver`, I remembered in the nested workspace discussion there were other workspace related sections that are not present. We now link out to `profile`, `patch`, and `replace`. In doing this, I realized that `patch` and `replace` do not specify their workspace behavior, so I do that. ### How should we test and review this PR? Look at it commit by commit to get more digestible chunks. Unfortunately, the first commit didn't split up so easily. ### Additional information Other information you want to mention in this PR, such as prior arts, future extensions, an unresolved problem, or a TODO list. --> <!-- homu-ignore:end -->
2 parents ef7ab8b + f39f8dc commit 362ce33

File tree

6 files changed

+114
-62
lines changed

6 files changed

+114
-62
lines changed

src/doc/src/reference/manifest.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -516,7 +516,7 @@ external tools may wish to use them in a consistent fashion, such as referring
516516
to the data in `workspace.metadata` if data is missing from `package.metadata`,
517517
if that makes sense for the tool in question.
518518

519-
[workspace-metadata]: workspaces.md#the-workspacemetadata-table
519+
[workspace-metadata]: workspaces.md#the-metadata-table
520520

521521
#### The `default-run` field
522522

@@ -603,7 +603,7 @@ more detail.
603603
"#the-required-features-field-optional": "cargo-targets.html#the-required-features-field",
604604
"#building-dynamic-or-static-libraries": "cargo-targets.html#the-crate-type-field",
605605
"#the-workspace-section": "workspaces.html#the-workspace-section",
606-
"#virtual-manifest": "workspaces.html",
606+
"#virtual-workspace": "workspaces.html",
607607
"#package-selection": "workspaces.html#package-selection",
608608
"#the-features-section": "features.html#the-features-section",
609609
"#rules": "features.html",

src/doc/src/reference/overriding-dependencies.md

+8
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,10 @@ also be patched with versions of crates that already exist. If a source is
291291
patched with a crate version that already exists in the source, then the
292292
source's original crate is replaced.
293293

294+
Cargo only looks at the patch settings in the `Cargo.toml` manifest at the
295+
root of the workspace. Patch settings defined in dependencies will be
296+
ignored.
297+
294298
### The `[replace]` section
295299

296300
> **Note**: `[replace]` is deprecated. You should use the
@@ -313,6 +317,10 @@ dependencies, except that you can't specify features. Note that when a crate
313317
is overridden the copy it's overridden with must have both the same name and
314318
version, but it can come from a different source (e.g., git or a local path).
315319

320+
Cargo only looks at the replace settings in the `Cargo.toml` manifest at the
321+
root of the workspace. Replace settings defined in dependencies will be
322+
ignored.
323+
316324
### `paths` overrides
317325

318326
Sometimes you're only temporarily working on a crate and you don't want to have

src/doc/src/reference/resolver.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -428,7 +428,7 @@ members = ["member1", "member2"]
428428
resolver = "2"
429429
```
430430

431-
[virtual workspace]: workspaces.md#virtual-manifest
431+
[virtual workspace]: workspaces.md#virtual-workspace
432432
[features-2]: features.md#feature-resolver-version-2
433433

434434
## Recommendations

src/doc/src/reference/specifying-dependencies.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -489,7 +489,7 @@ rand = { workspace = true, optional = true }
489489

490490
[crates.io]: https://crates.io/
491491
[dev-dependencies]: #development-dependencies
492-
[workspace.dependencies]: workspaces.md#the-workspacedependencies-table
492+
[workspace.dependencies]: workspaces.md#the-dependencies-table
493493
[optional]: features.md#optional-dependencies
494494
[features]: features.md
495495

src/doc/src/reference/unstable.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1358,7 +1358,7 @@ for more information.
13581358
### Workspace Inheritance
13591359

13601360
Workspace Inheritance has been stabilized in the 1.64 release.
1361-
See [workspace.package](workspaces.md#the-workspacepackage-table),
1362-
[workspace.dependencies](workspaces.md#the-workspacedependencies-table),
1361+
See [workspace.package](workspaces.md#the-package-table),
1362+
[workspace.dependencies](workspaces.md#the-dependencies-table),
13631363
and [inheriting-a-dependency-from-a-workspace](specifying-dependencies.md#inheriting-a-dependency-from-a-workspace)
1364-
for more information.
1364+
for more information.

src/doc/src/reference/workspaces.md

+99-55
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,86 @@
11
## Workspaces
22

3-
A *workspace* is a collection of one or more packages that share common
4-
dependency resolution (with a shared `Cargo.lock`), output directory, and
5-
various settings such as profiles. Packages that are part of a workspaces are
6-
called *workspace members*. There are two flavours of workspaces: as root
7-
package or as virtual manifest.
3+
A *workspace* is a collection of one or more packages, called *workspace
4+
members*, that are managed together.
85

9-
### Root package
6+
The key points of workspaces are:
7+
8+
* Common commands can run across all workspace members, like `cargo check --workspace`.
9+
* All packages share a common [`Cargo.lock`] file which resides in the
10+
*workspace root*.
11+
* All packages share a common [output directory], which defaults to a
12+
directory named `target` in the *workspace root*.
13+
* Sharing package metadata, like with [`workspace.package`](#the-package-table).
14+
* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
15+
sections in `Cargo.toml` are only recognized in the *root* manifest, and
16+
ignored in member crates' manifests.
17+
18+
In the `Cargo.toml`, the `[workspace]` table supports the following sections:
19+
20+
* [`[workspace]`](#the-workspace-section) — Defines a workspace.
21+
* [`resolver`](resolver.md#resolver-versions) — Sets the dependency resolver to use.
22+
* [`members`](#the-members-and-exclude-fields) — Packages to include in the workspace.
23+
* [`exclude`](#the-members-and-exclude-fields) — Packages to exclude from the workspace.
24+
* [`default-members`](#the-default-members-field) — Packages to operate on when a specific package wasn't selected.
25+
* [`package`](#the-package-table) — Keys for inheriting in packages.
26+
* [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies.
27+
* [`metadata`](#the-metadata-table) — Extra settings for external tools.
28+
* [`[patch]`](overriding-dependencies.md#the-patch-section) — Override dependencies.
29+
* [`[replace]`](overriding-dependencies.md#the-replace-section) — Override dependencies (deprecated).
30+
* [`[profile]`](profiles.md) — Compiler settings and optimizations.
31+
32+
### The `[workspace]` section
33+
34+
To create a workspace, you add the `[workspace]` table to a `Cargo.toml`:
35+
```toml
36+
[workspace]
37+
# ...
38+
```
1039

11-
A workspace can be created by adding a [`[workspace]`
12-
section](#the-workspace-section) to `Cargo.toml`. This can be added to a
13-
`Cargo.toml` that already defines a `[package]`, in which case the package is
40+
At minimum, a workspace has to have a member, either with a root package or as
41+
a virtual manifest.
42+
43+
#### Root package
44+
45+
If the [`[workspace]` section](#the-workspace-section) is added to a
46+
`Cargo.toml` that already defines a `[package]`, the package is
1447
the *root package* of the workspace. The *workspace root* is the directory
1548
where the workspace's `Cargo.toml` is located.
1649

17-
### Virtual manifest
50+
```toml
51+
[workspace]
52+
53+
[package]
54+
name = "hello_world" # the name of the package
55+
version = "0.1.0" # the current version, obeying semver
56+
authors = ["Alice <[email protected]>", "Bob <[email protected]>"]
57+
```
58+
59+
<a id="virtual-manifest"></a>
60+
#### Virtual workspace
1861

1962
Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section
2063
but without a [`[package]` section][package]. This is called a *virtual
2164
manifest*. This is typically useful when there isn't a "primary" package, or
2265
you want to keep all the packages organized in separate directories.
2366

24-
### Key features
25-
26-
The key points of workspaces are:
67+
```toml
68+
# [PROJECT_DIR]/Cargo.toml
69+
[workspace]
70+
members = ["hello_world"]
71+
```
2772

28-
* All packages share a common `Cargo.lock` file which resides in the
29-
*workspace root*.
30-
* All packages share a common [output directory], which defaults to a
31-
directory named `target` in the *workspace root*.
32-
* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
33-
sections in `Cargo.toml` are only recognized in the *root* manifest, and
34-
ignored in member crates' manifests.
73+
```toml
74+
# [PROJECT_DIR]/hello_world/Cargo.toml
75+
[package]
76+
name = "hello_world" # the name of the package
77+
version = "0.1.0" # the current version, obeying semver
78+
authors = ["Alice <[email protected]>", "Bob <[email protected]>"]
79+
```
3580

36-
### The `[workspace]` section
81+
### The `members` and `exclude` fields
3782

38-
The `[workspace]` table in `Cargo.toml` defines which packages are members of
83+
The `members` and `exclude` fields define which packages are members of
3984
the workspace:
4085

4186
```toml
@@ -56,26 +101,24 @@ workspace. This can be useful if some path dependencies aren't desired to be
56101
in the workspace at all, or using a glob pattern and you want to remove a
57102
directory.
58103

59-
An empty `[workspace]` table can be used with a `[package]` to conveniently
60-
create a workspace with the package and all of its path dependencies.
61-
62-
### Workspace selection
63-
64104
When inside a subdirectory within the workspace, Cargo will automatically
65105
search the parent directories for a `Cargo.toml` file with a `[workspace]`
66106
definition to determine which workspace to use. The [`package.workspace`]
67107
manifest key can be used in member crates to point at a workspace's root to
68108
override this automatic search. The manual setting can be useful if the member
69109
is not inside a subdirectory of the workspace root.
70110

71-
### Package selection
111+
#### Package selection
72112

73113
In a workspace, package-related cargo commands like [`cargo build`] can use
74114
the `-p` / `--package` or `--workspace` command-line flags to determine which
75115
packages to operate on. If neither of those flags are specified, Cargo will
76116
use the package in the current working directory. If the current directory is
77-
a virtual workspace, it will apply to all members (as if `--workspace` were
78-
specified on the command-line).
117+
a [virtual workspace](#virtual-workspace), it will apply to all members (as if
118+
`--workspace` were specified on the command-line). See also
119+
[`default-members`](#the-default-members-field).
120+
121+
### The `default-members` field
79122

80123
The optional `default-members` key can be specified to set the members to
81124
operate on when in the workspace root and the package selection flags are not
@@ -89,30 +132,7 @@ default-members = ["path/to/member2", "path/to/member3/foo"]
89132

90133
When specified, `default-members` must expand to a subset of `members`.
91134

92-
### The `workspace.metadata` table
93-
94-
The `workspace.metadata` table is ignored by Cargo and will not be warned
95-
about. This section can be used for tools that would like to store workspace
96-
configuration in `Cargo.toml`. For example:
97-
98-
```toml
99-
[workspace]
100-
members = ["member1", "member2"]
101-
102-
[workspace.metadata.webcontents]
103-
root = "path/to/webproject"
104-
tool = ["npm", "run", "build"]
105-
# ...
106-
```
107-
108-
There is a similar set of tables at the package level at
109-
[`package.metadata`][package-metadata]. While cargo does not specify a
110-
format for the content of either of these tables, it is suggested that
111-
external tools may wish to use them in a consistent fashion, such as referring
112-
to the data in `workspace.metadata` if data is missing from `package.metadata`,
113-
if that makes sense for the tool in question.
114-
115-
### The `workspace.package` table
135+
### The `package` table
116136

117137
The `workspace.package` table is where you define keys that can be
118138
inherited by members of a workspace. These keys can be inherited by
@@ -157,7 +177,7 @@ description.workspace = true
157177
documentation.workspace = true
158178
```
159179

160-
### The `workspace.dependencies` table
180+
### The `dependencies` table
161181

162182
The `workspace.dependencies` table is where you define dependencies to be
163183
inherited by members of a workspace.
@@ -196,7 +216,31 @@ cc.workspace = true
196216
rand.workspace = true
197217
```
198218

219+
### The `metadata` table
220+
221+
The `workspace.metadata` table is ignored by Cargo and will not be warned
222+
about. This section can be used for tools that would like to store workspace
223+
configuration in `Cargo.toml`. For example:
224+
225+
```toml
226+
[workspace]
227+
members = ["member1", "member2"]
228+
229+
[workspace.metadata.webcontents]
230+
root = "path/to/webproject"
231+
tool = ["npm", "run", "build"]
232+
# ...
233+
```
234+
235+
There is a similar set of tables at the package level at
236+
[`package.metadata`][package-metadata]. While cargo does not specify a
237+
format for the content of either of these tables, it is suggested that
238+
external tools may wish to use them in a consistent fashion, such as referring
239+
to the data in `workspace.metadata` if data is missing from `package.metadata`,
240+
if that makes sense for the tool in question.
241+
199242
[package]: manifest.md#the-package-section
243+
[`Cargo.lock`]: ../guide/cargo-toml-vs-cargo-lock.md
200244
[package-metadata]: manifest.md#the-metadata-table
201245
[output directory]: ../guide/build-cache.md
202246
[patch]: overriding-dependencies.md#the-patch-section

0 commit comments

Comments
 (0)