1## Workspaces
2
3A *workspace* is a collection of one or more packages that share common
4dependency resolution (with a shared `Cargo.lock`), output directory, and
5various settings such as profiles. Packages that are part of a workspaces are
6called *workspace members*. There are two flavours of workspaces: as root
7package or as virtual manifest.
8
9### Root package
10
11A workspace can be created by adding a [`[workspace]`
12section](#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
14the *root package* of the workspace. The *workspace root* is the directory
15where the workspace's `Cargo.toml` is located.
16
17### Virtual manifest
18
19Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section
20but without a [`[package]` section][package]. This is called a *virtual
21manifest*. This is typically useful when there isn't a "primary" package, or
22you want to keep all the packages organized in separate directories.
23
24### Key features
25
26The key points of workspaces are:
27
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.
35
36### The `[workspace]` section
37
38The `[workspace]` table in `Cargo.toml` defines which packages are members of
39the workspace:
40
41```toml
42[workspace]
43members = ["member1", "path/to/member2", "crates/*"]
44exclude = ["crates/foo", "path/to/other"]
45```
46
47All [`path` dependencies] residing in the workspace directory automatically
48become members. Additional members can be listed with the `members` key, which
49should be an array of strings containing directories with `Cargo.toml` files.
50
51The `members` list also supports [globs] to match multiple paths, using
52typical filename glob patterns like `*` and `?`.
53
54The `exclude` key can be used to prevent paths from being included in a
55workspace. This can be useful if some path dependencies aren't desired to be
56in the workspace at all, or using a glob pattern and you want to remove a
57directory.
58
59An empty `[workspace]` table can be used with a `[package]` to conveniently
60create a workspace with the package and all of its path dependencies.
61
62### Workspace selection
63
64When inside a subdirectory within the workspace, Cargo will automatically
65search the parent directories for a `Cargo.toml` file with a `[workspace]`
66definition to determine which workspace to use. The [`package.workspace`]
67manifest key can be used in member crates to point at a workspace's root to
68override this automatic search. The manual setting can be useful if the member
69is not inside a subdirectory of the workspace root.
70
71### Package selection
72
73In a workspace, package-related cargo commands like [`cargo build`] can use
74the `-p` / `--package` or `--workspace` command-line flags to determine which
75packages to operate on. If neither of those flags are specified, Cargo will
76use the package in the current working directory. If the current directory is
77a virtual workspace, it will apply to all members (as if `--workspace` were
78specified on the command-line).
79
80The optional `default-members` key can be specified to set the members to
81operate on when in the workspace root and the package selection flags are not
82used:
83
84```toml
85[workspace]
86members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
87default-members = ["path/to/member2", "path/to/member3/foo"]
88```
89
90When specified, `default-members` must expand to a subset of `members`.
91
92### The `workspace.metadata` table
93
94The `workspace.metadata` table is ignored by Cargo and will not be warned
95about. This section can be used for tools that would like to store workspace
96configuration in `Cargo.toml`. For example:
97
98```toml
99[workspace]
100members = ["member1", "member2"]
101
102[workspace.metadata.webcontents]
103root = "path/to/webproject"
104tool = ["npm", "run", "build"]
105# ...
106```
107
108There is a similar set of tables at the package level at
109[`package.metadata`][package-metadata]. While cargo does not specify a
110format for the content of either of these tables, it is suggested that
111external tools may wish to use them in a consistent fashion, such as referring
112to the data in `workspace.metadata` if data is missing from `package.metadata`,
113if that makes sense for the tool in question.
114
115[package]: manifest.md#the-package-section
116[package-metadata]: manifest.md#the-metadata-table
117[output directory]: ../guide/build-cache.md
118[patch]: overriding-dependencies.md#the-patch-section
119[replace]: overriding-dependencies.md#the-replace-section
120[profiles]: profiles.md
121[`path` dependencies]: specifying-dependencies.md#specifying-path-dependencies
122[`package.workspace`]: manifest.md#the-workspace-field
123[globs]: https://docs.rs/glob/0.3.0/glob/struct.Pattern.html
124[`cargo build`]: ../commands/cargo-build.md
125