From 870cae5217185fe6c08514ef1b37d3b580e5709a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 13 Sep 2022 10:44:55 -0500 Subject: [PATCH] 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 | 98 +++++++++++++------ 5 files changed, 75 insertions(+), 37 deletions(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 47aa6b824292..53de40c25733 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -516,7 +516,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 @@ -603,7 +603,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 047b81df79cb..22a45ded1c18 100644 --- a/src/doc/src/reference/resolver.md +++ b/src/doc/src/reference/resolver.md @@ -428,7 +428,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 15c705d68337..d6b4c6449dbb 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 a04c51fdc769..6570a61e52e3 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 bb3872265d15..354ee6fe7d53 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -3,39 +3,79 @@ 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. +called *workspace members*. -### Root package +The key points of workspaces are: + +* 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. -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 +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 + +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 ", "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. -### Key features - -The key points of workspaces are: +```toml +# [PROJECT_DIR]/Cargo.toml +[workspace] +members = ["hello_world"] +``` -* 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. +```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 `[workspace]` section +### The `members` and `exclude` fields -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 +96,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 +103,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 +127,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 +150,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 +195,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.