From 6a213f792e78e3142e801e5a43aff34161e18fa1 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 25 Apr 2024 14:09:26 -0500 Subject: [PATCH 1/6] docs(ref): Don't call out default-members is optional Nothing else in the files does despite it all being optional and this will be clearer in a follow up when I specify the defaults. --- src/doc/src/reference/workspaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index ad0d4175cee..d1509406be1 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -127,7 +127,7 @@ a [virtual workspace](#virtual-workspace), it will apply to all members (as if ## The `default-members` field -The optional `default-members` key can be specified to set the members to +The `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 used: From 0b15bef075eed921d3bfe460df9e965a6ef02c96 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 25 Apr 2024 14:10:38 -0500 Subject: [PATCH 2/6] docs(ref): Simplify default-members wording This will make it easier to make future changes --- src/doc/src/reference/workspaces.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index d1509406be1..d0050f7a27d 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -127,7 +127,7 @@ a [virtual workspace](#virtual-workspace), it will apply to all members (as if ## The `default-members` field -The `default-members` key can be specified to set the members to +The `default-members` field specifies the members to operate on when in the workspace root and the package selection flags are not used: From 58415ff288ee916078bf5c1e23076e388177f549 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 25 Apr 2024 14:27:37 -0500 Subject: [PATCH 3/6] docs(ref): Clarify default-members and members relationship The old statement that its a subset of `members` is incorrect because some members can be inferred and not show up in `members`. I tried to reword this to better convey the goal of what was being said --- src/doc/src/reference/workspaces.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index d0050f7a27d..dc846d073ed 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -127,7 +127,7 @@ a [virtual workspace](#virtual-workspace), it will apply to all members (as if ## The `default-members` field -The `default-members` field specifies the members to +The `default-members` field specifies paths of [members](#the-members-and-exclude-fields) to operate on when in the workspace root and the package selection flags are not used: @@ -137,8 +137,6 @@ members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] default-members = ["path/to/member2", "path/to/member3/foo"] ``` -When specified, `default-members` must expand to a subset of `members`. - ## The `package` table The `workspace.package` table is where you define keys that can be From 2289026d70bf32ed422751be9d0118d0abd47ad7 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 25 Apr 2024 14:30:18 -0500 Subject: [PATCH 4/6] docs(ref): Move default-members defalting to default-members This also tweaks the wording to be clear that `default-members` always apply in the workspace root, not just for virtual workspaces. --- src/doc/src/reference/workspaces.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index dc846d073ed..d70f4bc0a5c 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -120,10 +120,8 @@ is not inside a subdirectory of the workspace root. 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](#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). +use the package in the current working directory. However, if the current directory is +a workspace root, the [`default-members`](#the-default-members-field) will be used. ## The `default-members` field @@ -137,6 +135,10 @@ members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] default-members = ["path/to/member2", "path/to/member3/foo"] ``` +When unspecified, the [root package](#root-package) will be used. +In the case of a [virtual workspace](#virtual-workspace), all members will be used +(as if `--workspace` were specified on the command-line). + ## The `package` table The `workspace.package` table is where you define keys that can be From 50adf47c18fc3a6ea3ecb09135f859ef0d03a528 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Thu, 25 Apr 2024 14:21:30 -0500 Subject: [PATCH 5/6] docs(ref): Add a caution about default-members with root package --- src/doc/src/reference/workspaces.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index d70f4bc0a5c..32dc59b77e2 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -135,6 +135,9 @@ members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] default-members = ["path/to/member2", "path/to/member3/foo"] ``` +> Note: when a [root package](#root-package) is present, +> you can only operate on it using `--package` and `--workspace` flags. + When unspecified, the [root package](#root-package) will be used. In the case of a [virtual workspace](#virtual-workspace), all members will be used (as if `--workspace` were specified on the command-line). From 5f5e0fc50496975188907b721a33481e4ab777bd Mon Sep 17 00:00:00 2001 From: Ed Page Date: Tue, 23 Apr 2024 15:14:33 -0500 Subject: [PATCH 6/6] docs(ref): Index differences between virtual / real manifests For a user to read the reference and to understand when each type of workspace might be right for them, they have to know to also read the section on Package Selection. This reframes the section on needing to set `resolver = "2"` to being about differences when there isn't a root package and extends it to summarize a part of Package Selection, linking out to it. The hope is that this will make it all of the differences more discoverable without retreading too much of the same ground within Reference-style documentation. Part of #13580 --- src/doc/src/reference/workspaces.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 32dc59b77e2..e15326b643b 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -80,10 +80,14 @@ edition = "2021" # the edition, will have no effect on a resolver used in th authors = ["Alice ", "Bob "] ``` -Note that in a virtual manifest the [`resolver = "2"`](resolver.md#resolver-versions) -should be specified manually. It is usually deduced from the [`package.edition`][package-edition] -field which is absent in virtual manifests and the edition field of a member -won't affect the resolver used by the workspace. +By having a workspace without a root package, + +- [`resolver`](resolver.md#resolver-versions) must be + set explicitly in virtual workspaces as they have no + [`package.edition`][package-edition] to infer it from + [resolver version](resolver.md#resolver-versions). +- Commands run in the workspace root will run against all workspace + members by default, see [`default-members`](#the-default-members-field). ## The `members` and `exclude` fields