1
1
## Workspaces
2
2
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.
8
5
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
+ ```
10
39
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
14
47
the * root package* of the workspace. The * workspace root* is the directory
15
48
where the workspace's ` Cargo.toml ` is located.
16
49
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
+
57
+ ```
58
+
59
+ <a id =" virtual-manifest " ></a >
60
+ #### Virtual workspace
18
61
19
62
Alternatively, a ` Cargo.toml ` file can be created with a ` [workspace] ` section
20
63
but without a [ ` [package] ` section] [ package ] . This is called a * virtual
21
64
manifest* . This is typically useful when there isn't a "primary" package, or
22
65
you want to keep all the packages organized in separate directories.
23
66
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
+ ```
27
72
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
+
79
+ ```
35
80
36
- ### The ` [workspace] ` section
81
+ ### The ` members ` and ` exclude ` fields
37
82
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
39
84
the workspace:
40
85
41
86
``` toml
@@ -56,26 +101,24 @@ workspace. This can be useful if some path dependencies aren't desired to be
56
101
in the workspace at all, or using a glob pattern and you want to remove a
57
102
directory.
58
103
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
-
64
104
When inside a subdirectory within the workspace, Cargo will automatically
65
105
search the parent directories for a ` Cargo.toml ` file with a ` [workspace] `
66
106
definition to determine which workspace to use. The [ ` package.workspace ` ]
67
107
manifest key can be used in member crates to point at a workspace's root to
68
108
override this automatic search. The manual setting can be useful if the member
69
109
is not inside a subdirectory of the workspace root.
70
110
71
- ### Package selection
111
+ #### Package selection
72
112
73
113
In a workspace, package-related cargo commands like [ ` cargo build ` ] can use
74
114
the ` -p ` / ` --package ` or ` --workspace ` command-line flags to determine which
75
115
packages to operate on. If neither of those flags are specified, Cargo will
76
116
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
79
122
80
123
The optional ` default-members ` key can be specified to set the members to
81
124
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"]
89
132
90
133
When specified, ` default-members ` must expand to a subset of ` members ` .
91
134
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
116
136
117
137
The ` workspace.package ` table is where you define keys that can be
118
138
inherited by members of a workspace. These keys can be inherited by
@@ -157,7 +177,7 @@ description.workspace = true
157
177
documentation.workspace = true
158
178
```
159
179
160
- ### The ` workspace. dependencies` table
180
+ ### The ` dependencies ` table
161
181
162
182
The ` workspace.dependencies ` table is where you define dependencies to be
163
183
inherited by members of a workspace.
@@ -196,7 +216,31 @@ cc.workspace = true
196
216
rand.workspace = true
197
217
```
198
218
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
+
199
242
[ package ] : manifest.md#the-package-section
243
+ [ `Cargo.lock` ] : ../guide/cargo-toml-vs-cargo-lock.md
200
244
[ package-metadata ] : manifest.md#the-metadata-table
201
245
[ output directory ] : ../guide/build-cache.md
202
246
[ patch ] : overriding-dependencies.md#the-patch-section
0 commit comments