Improve Workspaces docs page

[rimutaka]

Problem

https://doc.rust-lang.org/cargo/reference/workspaces.html is comprehensive, but could benefit from some clarifications and examples of how to create a workspace

Anyone trying to create a workspace would have to piece together multiple code snippets and go by trial and error.
Most people probably get it right the first time, but making it clearer in the docs will help.

Proposed Solution

• explain the behavior of a root package (root mainfest, it has different names even in the source code 😓).
• explain the resolver part where it is first mentioned
• add examples of creating a workspace step-by-step, manual and/or using cargo commands
• consider https://matklad.github.io/2021/08/22/large-rust-workspaces.html

Copied from and earlier discussion (#13579 (comment))

Notes

Related:

• Stems from Improve workspace resolver error message when root edition is missing #13579
• Add cargo new --workspace to create a workspace #8365
• Feature request: Cargo templates #5151
• cargo init is not working great when creating a new workspace with multiple members #11234

[weihanglo]

We can deal with each proposed solution per pull request.

• explain the behavior of a root package (or primary package or root mainfest, it has different names even in the source code 😓).

This might be the easiest one, by expanding this Root package section, though not sure what needs to be captured. I can think of one: root package becomes the default workspace member when no other specified.

• explain the resolver part where it is first mentioned

This could be as simple as a link to Resolver versions section, if I understand correctly.

• add examples of creating a workspace step-by-step, manual and/or using cargo commands
• consider https://matklad.github.io/2021/08/22/large-rust-workspaces.html

These are covered by #11234 I believe.

While I am going to mark this as S-accepted, documenting Cargo's behavior often requires a deep understanding of Cargo. It implies more back-and-forth between contributors and maintainers in discussion if there are gaps between their familiarities in Cargo.

[heisen-li]

I may not have understood it accurately in this regard, but I'd like to try to address it. @rustbot claim

[heisen-li]

explain the resolver part where it is first mentioned

Cargo book workspace The chapters are already given a link when they first appear, so it seems like there's no need for extra explanation or link? Could it be that I'm missing something?

[workspace] — Defines a workspace.

• resolver — Sets the dependency resolver to use.
  ...

[heisen-li]

From the comment.

Cargo Guide:

This guide will give you all that you need to know about how to use Cargo to develop Rust packages.

Cargo Reference:

The reference covers the details of various areas of Cargo.

Maybe Cargo Reference is more appropriate?

But I seem to have found something else.I looked at the previous chapters and realized that in 3.1 Specifying Dependencies mentions a lot of workspaces and may need to reorder the chapters. For example, put the 3.3 Workspaces section in front.

add examples of creating a workspace step-by-step, manual and/or using cargo commands
consider https://matklad.github.io/2021/08/22/large-rust-workspaces.html

In addition, it occurred to me that I could add a sub-section Creating a Workspace Example to Workspaces, as in 3.4.1 Features Examples and 3.8.1 Build Script Examples。

[heisen-li]

@epage @weihanglo , I've written a rough post to show my plan and would like your advice.

---

Creating a New Workspace

In this chapter we implement the creation of a workspace new_workspace from scratch, in which two members foo-bin and bar-lib are included.

As mentioned in [workspace] section, the workspace must have at least one member, either the root package or a virtual manifest. Here we recommend setting the root of the workspace to be a virtual manifest. The reason is as follows:

• The crate namespace at the Cargo level is flat. The tree layout creates another hierarchy and increases the possibility of inconsistencies.
• With a flat structure, adding or splitting crates is very easy.
• Even larger flattened lists are easier to see at a glance and easier to maintain than smaller tree structures.

Let's look at how a workspace containing a virtual inventory should be created.

Currently Cargo does not provide automatic creation of workspaces using the command line. You need to create the Cargo.toml file under the folder new_workspace:

# [new_workspace]/Cargo.toml
[workspace]

If using a virtual workspace, then the version of resolver needs to be specified in the table (if not, the default version of resolver for a workspace is 1, even if the default resolver version for workspace members is 2), for example:

[workspace]
resolver = "2"

You can then proceed to create workspace members. As mentioned above, if you have a lot of workspace members, we recommend designing the workspace with a flat structure. So add all the workspace members in the directory new_workspace/crates.

There are several ways to add members to the workspace, we recommend using the command cargo new/init. For example, add the members foo-bin and bar-lib to the workspace:

$ cargo new crates/foo-bin
$ cargo new crates/bar-lib

Cargo will automatically add members to Cargo.toml:

# [new_workspace]/Cargo.toml
[workspace]
resolver = "2"
members = [ "bar-lib","foo-bin"]

[package]
...

The project at this point contains the following files:

$ cd new_workspace
$ tree .
.
├── Cargo.toml
└── crates
    ├── bar-lib
    │   ├── Cargo.toml
    │   └── src
    │       └── main.rs
    └── foo-bin
        ├── Cargo.toml
        └── src
            └── main.rs

5 directories, 5 files

Up to this point, we have achieved creating a workspace that contains multiple crate members through a step-by-step process.

[epage]

Maybe Cargo Reference is more appropriate?

In addition, it occurred to me that I could add a sub-section Creating a Workspace Example to Workspaces, as in 3.4.1 Features Examples and 3.8.1 Build Script Examples。

If we're adding a how-to to the reference, that feels backwards and out of place.

The existing "examples" sections are showing practices related to the reference, not tutorial-level documentation. We could likely add one of those for workspaces but that is different than "Creating a workspace". If we add a section hanging off of the reference, it would more likely be related to #11234. This would also accomplish the high level goal set out in this issue (showing a cohesive picture of workspaces).

But I seem to have found something else.I looked at the previous chapters and realized that in 3.1 Specifying Dependencies mentions a lot of workspaces and may need to reorder the chapters. For example, put the 3.3 Workspaces section in front.

Personally, I'm not too worried about the exact ordering of the reference as it is reference level material and cross-references itself all over the place. There isn't really a clear "start with this"

[heisen-li]

So, is it possible to reach a consensus on the following.

The location of the new section is 2.3 Creating a New Workspace. And, if it involves something that's ahead of its time, use a link to refer to it. The general content of the addition is the content of my earlier first draft.

Are there any other suggestions to discuss? If not can I proceed to the next step and submit a PR?