From a67c465da21287e1e880882ab8db606dc0b89a15 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 10:44:55 -0500 Subject: [PATCH 1/9] docs(ref): Re-org workspace docs to be like package docs In looking over #10625, I remembered we've been having growing pains with the workspace documentation. It was originally written when there were a lot fewer workspace features. As more workspace features have been added, they've been tacked on to the documentation. This re-thinks the documentation by focusing on the schema, much like `manifest.md` does. --- src/doc/src/reference/manifest.md | 4 +- src/doc/src/reference/resolver.md | 2 +- .../src/reference/specifying-dependencies.md | 2 +- src/doc/src/reference/unstable.md | 6 +- src/doc/src/reference/workspaces.md | 101 ++++++++++++------ 5 files changed, 77 insertions(+), 38 deletions(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index e239042dc..cdc1bd1c3 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -512,7 +512,7 @@ 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. -[workspace-metadata]: workspaces.md#the-workspacemetadata-table +[workspace-metadata]: workspaces.md#the-metadata-table #### The `default-run` field @@ -599,7 +599,7 @@ more detail. "#the-required-features-field-optional": "cargo-targets.html#the-required-features-field", "#building-dynamic-or-static-libraries": "cargo-targets.html#the-crate-type-field", "#the-workspace-section": "workspaces.html#the-workspace-section", - "#virtual-manifest": "workspaces.html", + "#virtual-workspace": "workspaces.html", "#package-selection": "workspaces.html#package-selection", "#the-features-section": "features.html#the-features-section", "#rules": "features.html", diff --git a/src/doc/src/reference/resolver.md b/src/doc/src/reference/resolver.md index d3476d083..c66541d4d 100644 --- a/src/doc/src/reference/resolver.md +++ b/src/doc/src/reference/resolver.md @@ -427,7 +427,7 @@ members = ["member1", "member2"] resolver = "2" ``` -[virtual workspace]: workspaces.md#virtual-manifest +[virtual workspace]: workspaces.md#virtual-workspace [features-2]: features.md#feature-resolver-version-2 ## Recommendations diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index 36ddf0dbb..8e3dbf1bc 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -489,7 +489,7 @@ rand = { workspace = true, optional = true } [crates.io]: https://crates.io/ [dev-dependencies]: #development-dependencies -[workspace.dependencies]: workspaces.md#the-workspacedependencies-table +[workspace.dependencies]: workspaces.md#the-dependencies-table [optional]: features.md#optional-dependencies [features]: features.md diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index a04c51fdc..6570a61e5 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -1358,7 +1358,7 @@ for more information. ### Workspace Inheritance Workspace Inheritance has been stabilized in the 1.64 release. -See [workspace.package](workspaces.md#the-workspacepackage-table), -[workspace.dependencies](workspaces.md#the-workspacedependencies-table), +See [workspace.package](workspaces.md#the-package-table), +[workspace.dependencies](workspaces.md#the-dependencies-table), and [inheriting-a-dependency-from-a-workspace](specifying-dependencies.md#inheriting-a-dependency-from-a-workspace) -for more information. \ No newline at end of file +for more information. diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index bb3872265..cc378d2b7 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -3,25 +3,7 @@ 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. - -### Root package - -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 -the *root package* of the workspace. The *workspace root* is the directory -where the workspace's `Cargo.toml` is located. - -### Virtual manifest - -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 +called *workspace members*. The key points of workspaces are: @@ -33,9 +15,68 @@ The key points of workspaces are: 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. + * [`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. + * [`metadata`](#the-metadata-table) — Extra settings for external tools. + * [`package`](#the-package-table) — Keys for inheriting in packages. + * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies. + ### The `[workspace]` section -The `[workspace]` table in `Cargo.toml` defines which packages are members of +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. + +```toml +[workspace] + +[package] +name = "hello_world" # the name of the package +version = "0.1.0" # the current version, obeying semver +authors = ["Alice ", "Bob "] +``` + + +#### 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. + +```toml +# [PROJECT_DIR]/Cargo.toml +[workspace] +members = ["hello_world"] +``` + +```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 ", "Bob "] +``` + +### The `members` and `exclude` fields + +The `members` and `exclude` fields define which packages are members of the workspace: ```toml @@ -56,11 +97,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 +104,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,7 +128,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 `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 @@ -112,7 +151,7 @@ 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 +196,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. From c0da05502a0c924ed0f15518e6e0f75a8ec1be89 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 10:48:30 -0500 Subject: [PATCH 2/9] docs(ref): Have workspace docs link out to resolver field docs This is a part of the schema we were missing. A first step before encouraging people to use it is to document it! --- src/doc/src/reference/workspaces.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index cc378d2b7..db7f050b3 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -18,6 +18,7 @@ The key points of workspaces are: 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. From 10c3bea79412fad1278fbb4491c8d2aa29211d81 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 10:52:34 -0500 Subject: [PATCH 3/9] docs(ref): Have workspace docs link out to profile section docs In a workspace, only the workspace's profile is respected. This is already documented in the profile documentation but we should raise visibility of it within the workspace documentation. --- src/doc/src/reference/workspaces.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index db7f050b3..ec351bbb6 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -25,6 +25,7 @@ In the `Cargo.toml`, the `[workspace]` table supports the following sections: * [`metadata`](#the-metadata-table) — Extra settings for external tools. * [`package`](#the-package-table) — Keys for inheriting in packages. * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies. +* [`[profile]`](profiles.md) — Compiler settings and optimizations. ### The `[workspace]` section From 7962dae3988eed1b29815871a3a7f3e5a0f699f9 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 11:01:04 -0500 Subject: [PATCH 4/9] docs(ref): Have workspace docs link out to patch/replace docs The workspace behavior doesn't seem to be documented at all, so a blurb was brought in that is like the profile blurb. The workspace docs then link out to it so users can be aware of this special workspace behavior. --- src/doc/src/reference/overriding-dependencies.md | 8 ++++++++ src/doc/src/reference/workspaces.md | 2 ++ 2 files changed, 10 insertions(+) diff --git a/src/doc/src/reference/overriding-dependencies.md b/src/doc/src/reference/overriding-dependencies.md index 504811d5b..d3e2fa42a 100644 --- a/src/doc/src/reference/overriding-dependencies.md +++ b/src/doc/src/reference/overriding-dependencies.md @@ -291,6 +291,10 @@ also be patched with versions of crates that already exist. If a source is patched with a crate version that already exists in the source, then the source's original crate is replaced. +Cargo only looks at the patch settings in the `Cargo.toml` manifest at the +root of the workspace. Patch settings defined in dependencies will be +ignored. + ### The `[replace]` section > **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 is overridden the copy it's overridden with must have both the same name and version, but it can come from a different source (e.g., git or a local path). +Cargo only looks at the replace settings in the `Cargo.toml` manifest at the +root of the workspace. Replace settings defined in dependencies will be +ignored. + ### `paths` overrides Sometimes you're only temporarily working on a crate and you don't want to have diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index ec351bbb6..b0164e9a4 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -25,6 +25,8 @@ In the `Cargo.toml`, the `[workspace]` table supports the following sections: * [`metadata`](#the-metadata-table) — Extra settings for external tools. * [`package`](#the-package-table) — Keys for inheriting in packages. * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies. +* [`[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 From cfd1c7eb4a5cfd1a1c62de35b507865eb2972a64 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 12:02:11 -0500 Subject: [PATCH 5/9] docs(ref): Move metadata to last --- src/doc/src/reference/workspaces.md | 48 ++++++++++++++--------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index b0164e9a4..0d764a5c5 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -22,9 +22,9 @@ In the `Cargo.toml`, the `[workspace]` table supports the following sections: * [`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. - * [`metadata`](#the-metadata-table) — Extra settings for external tools. * [`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. @@ -132,29 +132,6 @@ default-members = ["path/to/member2", "path/to/member3/foo"] When specified, `default-members` must expand to a subset of `members`. -### 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. - ### The `package` table The `workspace.package` table is where you define keys that can be @@ -239,6 +216,29 @@ 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 [package-metadata]: manifest.md#the-metadata-table [output directory]: ../guide/build-cache.md From 5b950a3ecf9b8cad857361b81b4b92fd6bdbdafb Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 14:03:02 -0500 Subject: [PATCH 6/9] docs(ref): Remove redundant workspace description --- src/doc/src/reference/workspaces.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 0d764a5c5..376c3226d 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -1,9 +1,7 @@ ## 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*. +A *workspace* is a collection of one or more packages, called *workspace +members*, that are managed together. The key points of workspaces are: From 2bcf1a70b4fe1f8d620c7638a9da53e5798f1091 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 14:04:59 -0500 Subject: [PATCH 7/9] docs(ref): Add --workspace as a key point This is a frequent reason I use them --- src/doc/src/reference/workspaces.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 376c3226d..4a234b884 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -5,6 +5,7 @@ members*, that are managed together. The key points of workspaces are: +* 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 From 7997f1e9cf4b4e8a582d559a77744ec36a5e4ed5 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 14:06:17 -0500 Subject: [PATCH 8/9] docs(ref): Include workspace inheritane --- src/doc/src/reference/workspaces.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 4a234b884..867596bed 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -10,6 +10,7 @@ The key points of workspaces are: *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. From a1c48c56fe5c2dfa98ad35d479fd5496413dcf94 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 14:08:01 -0500 Subject: [PATCH 9/9] docs(ref): Provide path for people to finding why shared Cargo.lock matters --- src/doc/src/reference/workspaces.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 867596bed..03e7b02ff 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -6,7 +6,7 @@ members*, that are managed together. The key points of workspaces are: * Common commands can run across all workspace members, like `cargo check --workspace`. -* All packages share a common `Cargo.lock` file which resides in the +* 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*. @@ -240,6 +240,7 @@ 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