|
|
|
@ -1,41 +1,86 @@
|
|
|
|
|
## Workspaces
|
|
|
|
|
|
|
|
|
|
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* is a collection of one or more packages, called *workspace
|
|
|
|
|
members*, that are managed together.
|
|
|
|
|
|
|
|
|
|
### Root package
|
|
|
|
|
The key points of workspaces are:
|
|
|
|
|
|
|
|
|
|
A workspace can be created by adding a [`[workspace]`
|
|
|
|
|
section](#the-workspace-section) to `Cargo.toml`. This can be added to a
|
|
|
|
|
`Cargo.toml` that already defines a `[package]`, in which case the package is
|
|
|
|
|
* Common commands can run across all workspace members, like `cargo check --workspace`.
|
|
|
|
|
* All packages share a common [`Cargo.lock`] file which resides in the
|
|
|
|
|
*workspace root*.
|
|
|
|
|
* All packages share a common [output directory], which defaults to a
|
|
|
|
|
directory named `target` in the *workspace root*.
|
|
|
|
|
* Sharing package metadata, like with [`workspace.package`](#the-package-table).
|
|
|
|
|
* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
|
|
|
|
|
sections in `Cargo.toml` are only recognized in the *root* manifest, and
|
|
|
|
|
ignored in member crates' manifests.
|
|
|
|
|
|
|
|
|
|
In the `Cargo.toml`, the `[workspace]` table supports the following sections:
|
|
|
|
|
|
|
|
|
|
* [`[workspace]`](#the-workspace-section) — Defines a workspace.
|
|
|
|
|
* [`resolver`](resolver.md#resolver-versions) — Sets the dependency resolver to use.
|
|
|
|
|
* [`members`](#the-members-and-exclude-fields) — Packages to include in the workspace.
|
|
|
|
|
* [`exclude`](#the-members-and-exclude-fields) — Packages to exclude from the workspace.
|
|
|
|
|
* [`default-members`](#the-default-members-field) — Packages to operate on when a specific package wasn't selected.
|
|
|
|
|
* [`package`](#the-package-table) — Keys for inheriting in packages.
|
|
|
|
|
* [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies.
|
|
|
|
|
* [`metadata`](#the-metadata-table) — Extra settings for external tools.
|
|
|
|
|
* [`[patch]`](overriding-dependencies.md#the-patch-section) — Override dependencies.
|
|
|
|
|
* [`[replace]`](overriding-dependencies.md#the-replace-section) — Override dependencies (deprecated).
|
|
|
|
|
* [`[profile]`](profiles.md) — Compiler settings and optimizations.
|
|
|
|
|
|
|
|
|
|
### The `[workspace]` section
|
|
|
|
|
|
|
|
|
|
To create a workspace, you add the `[workspace]` table to a `Cargo.toml`:
|
|
|
|
|
```toml
|
|
|
|
|
[workspace]
|
|
|
|
|
# ...
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
At minimum, a workspace has to have a member, either with a root package or as
|
|
|
|
|
a virtual manifest.
|
|
|
|
|
|
|
|
|
|
#### Root package
|
|
|
|
|
|
|
|
|
|
If the [`[workspace]` section](#the-workspace-section) is added to a
|
|
|
|
|
`Cargo.toml` that already defines a `[package]`, the package is
|
|
|
|
|
the *root package* of the workspace. The *workspace root* is the directory
|
|
|
|
|
where the workspace's `Cargo.toml` is located.
|
|
|
|
|
|
|
|
|
|
### Virtual manifest
|
|
|
|
|
```toml
|
|
|
|
|
[workspace]
|
|
|
|
|
|
|
|
|
|
[package]
|
|
|
|
|
name = "hello_world" # the name of the package
|
|
|
|
|
version = "0.1.0" # the current version, obeying semver
|
|
|
|
|
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
<a id="virtual-manifest"></a>
|
|
|
|
|
#### Virtual workspace
|
|
|
|
|
|
|
|
|
|
Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section
|
|
|
|
|
but without a [`[package]` section][package]. 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.
|
|
|
|
|
|
|
|
|
|
### Key features
|
|
|
|
|
```toml
|
|
|
|
|
# [PROJECT_DIR]/Cargo.toml
|
|
|
|
|
[workspace]
|
|
|
|
|
members = ["hello_world"]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The key points of workspaces are:
|
|
|
|
|
```toml
|
|
|
|
|
# [PROJECT_DIR]/hello_world/Cargo.toml
|
|
|
|
|
[package]
|
|
|
|
|
name = "hello_world" # the name of the package
|
|
|
|
|
version = "0.1.0" # the current version, obeying semver
|
|
|
|
|
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
* All packages share a common `Cargo.lock` file which resides in the
|
|
|
|
|
*workspace root*.
|
|
|
|
|
* All packages share a common [output directory], which defaults to a
|
|
|
|
|
directory named `target` in the *workspace root*.
|
|
|
|
|
* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
|
|
|
|
|
sections in `Cargo.toml` are only recognized in the *root* manifest, and
|
|
|
|
|
ignored in member crates' manifests.
|
|
|
|
|
### The `members` and `exclude` fields
|
|
|
|
|
|
|
|
|
|
### The `[workspace]` section
|
|
|
|
|
|
|
|
|
|
The `[workspace]` table in `Cargo.toml` defines which packages are members of
|
|
|
|
|
The `members` and `exclude` fields define which packages are members of
|
|
|
|
|
the workspace:
|
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
@ -56,11 +101,6 @@ 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
|
|
|
|
|
directory.
|
|
|
|
|
|
|
|
|
|
An empty `[workspace]` table can be used with a `[package]` to conveniently
|
|
|
|
|
create a workspace with the package and all of its path dependencies.
|
|
|
|
|
|
|
|
|
|
### Workspace selection
|
|
|
|
|
|
|
|
|
|
When inside a subdirectory within the workspace, Cargo will automatically
|
|
|
|
|
search the parent directories for a `Cargo.toml` file with a `[workspace]`
|
|
|
|
|
definition to determine which workspace to use. The [`package.workspace`]
|
|
|
|
@ -68,14 +108,17 @@ 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.
|
|
|
|
|
|
|
|
|
|
### Package selection
|
|
|
|
|
#### Package selection
|
|
|
|
|
|
|
|
|
|
In a workspace, package-related cargo commands like [`cargo build`] can use
|
|
|
|
|
the `-p` / `--package` or `--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 `--workspace` were
|
|
|
|
|
specified on the command-line).
|
|
|
|
|
a [virtual workspace](#virtual-workspace), it will apply to all members (as if
|
|
|
|
|
`--workspace` were specified on the command-line). See also
|
|
|
|
|
[`default-members`](#the-default-members-field).
|
|
|
|
|
|
|
|
|
|
### The `default-members` field
|
|
|
|
|
|
|
|
|
|
The optional `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
|
|
|
|
@ -89,30 +132,7 @@ default-members = ["path/to/member2", "path/to/member3/foo"]
|
|
|
|
|
|
|
|
|
|
When specified, `default-members` must expand to a subset of `members`.
|
|
|
|
|
|
|
|
|
|
### The `workspace.metadata` table
|
|
|
|
|
|
|
|
|
|
The `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
|
|
|
|
|
configuration in `Cargo.toml`. For example:
|
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[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`][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 `package.metadata`,
|
|
|
|
|
if that makes sense for the tool in question.
|
|
|
|
|
|
|
|
|
|
### The `workspace.package` table
|
|
|
|
|
### The `package` table
|
|
|
|
|
|
|
|
|
|
The `workspace.package` table is where you define keys that can be
|
|
|
|
|
inherited by members of a workspace. These keys can be inherited by
|
|
|
|
@ -157,7 +177,7 @@ description.workspace = true
|
|
|
|
|
documentation.workspace = true
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### The `workspace.dependencies` table
|
|
|
|
|
### The `dependencies` table
|
|
|
|
|
|
|
|
|
|
The `workspace.dependencies` table is where you define dependencies to be
|
|
|
|
|
inherited by members of a workspace.
|
|
|
|
@ -196,7 +216,31 @@ cc.workspace = true
|
|
|
|
|
rand.workspace = true
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### The `metadata` table
|
|
|
|
|
|
|
|
|
|
The `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
|
|
|
|
|
configuration in `Cargo.toml`. For example:
|
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[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`][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 `package.metadata`,
|
|
|
|
|
if that makes sense for the tool in question.
|
|
|
|
|
|
|
|
|
|
[package]: manifest.md#the-package-section
|
|
|
|
|
[`Cargo.lock`]: ../guide/cargo-toml-vs-cargo-lock.md
|
|
|
|
|
[package-metadata]: manifest.md#the-metadata-table
|
|
|
|
|
[output directory]: ../guide/build-cache.md
|
|
|
|
|
[patch]: overriding-dependencies.md#the-patch-section
|
|
|
|
|