A workspace is a collection of one or more packages that share common
dependency resolution (with a shared
Cargo.lock), output directory, and
various settings such as profiles. Packages that are part of a workspaces are
called workspace members. There are two flavours of workspaces: as root
package or as virtual manifest.
A workspace can be created by adding a
Cargo.toml. This can be added to a
Cargo.toml that already defines a
[package], in which case the package is
the root package of the workspace. The workspace root is the directory
where the workspace's
Cargo.toml is located.
Cargo.toml file can be created with a
but without a
[package] section. This is called a virtual
manifest. This is typically useful when there isn't a "primary" package, or
you want to keep all the packages organized in separate directories.
The key points of workspaces are:
- All packages share a common
Cargo.lockfile which resides in the workspace root.
- All packages share a common output directory, which defaults to a
targetin the workspace root.
Cargo.tomlare only recognized in the root manifest, and ignored in member crates' manifests.
[workspace] table in
Cargo.toml defines which packages are members of
[workspace] members = ["member1", "path/to/member2", "crates/*"] exclude = ["crates/foo", "path/to/other"]
path dependencies residing in the workspace directory automatically
become members. Additional members can be listed with the
members key, which
should be an array of strings containing directories with
members list also supports globs to match multiple paths, using
typical filename glob patterns like
exclude key can be used to prevent paths from being included in a
workspace. This can be useful if some path dependencies aren't desired to be
in the workspace at all, or using a glob pattern and you want to remove a
[workspace] table can be used with a
[package] to conveniently
create a workspace with the package and all of its path dependencies.
When inside a subdirectory within the workspace, Cargo will automatically
search the parent directories for a
Cargo.toml file with a
definition to determine which workspace to use. The
manifest key can be used in member crates to point at a workspace's root to
override this automatic search. The manual setting can be useful if the member
is not inside a subdirectory of the workspace root.
In a workspace, package-related cargo commands like
cargo build can use
--workspace command-line flags to determine which
packages to operate on. If neither of those flags are specified, Cargo will
use the package in the current working directory. If the current directory is
a virtual workspace, it will apply to all members (as if
specified on the command-line).
default-members key can be specified to set the members to
operate on when in the workspace root and the package selection flags are not
[workspace] members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] default-members = ["path/to/member2", "path/to/member3/foo"]
default-members must expand to a subset of
workspace.metadata table is ignored by Cargo and will not be warned
about. This section can be used for tools that would like to store workspace
Cargo.toml. For example:
[workspace] members = ["member1", "member2"] [workspace.metadata.webcontents] root = "path/to/webproject" tool = ["npm", "run", "build"] # ...
There is a similar set of tables at the package level at
package.metadata. While cargo does not specify a
format for the content of either of these tables, it is suggested that
external tools may wish to use them in a consistent fashion, such as referring
to the data in
workspace.metadata if data is missing from
if that makes sense for the tool in question.