Perhaps cargo new should have a [workspace] tag?

[abmpicoli]

Problem

As I've worked through the cargo book, and started working at another chapters, I got a surprise by the lack of awareness of the concept of cargo workspaces. This is discussed in the book project issue rust-lang/book#3779 .

Basically I inadvertedly added one "rust project" inside another. I didn't know that the cargo.toml files are not "isolated" by themselves, and keep looking for workspace tags in the parent directories. This is never explained in the 1st chapter of the cargo book, and got me into a puzzling experience , discussed in the forum https://users.rust-lang.org/t/what-is-the-correlation-between-two-cargo-toml-in-the-file-hierarchy/101933/11

Proposed Solution

The proposed solution is that cargo new should create empty workspaces by default, making beginner projects to be standalone projects.

https://users.rust-lang.org/t/what-is-the-correlation-between-two-cargo-toml-in-the-file-hierarchy/101933/8

And the book project should make a very simple and quick explanation of workspaces directly at the hello cargo chapter. As discussed in the book issue mentioned before.

Notes

No response

[epage]

Workspaces aren't immediately covered because they are for bigger, more complex cases.

As for cargo new this would counter to our improving it for workspace users. First, we want to detect if it looks like its a workspace member and set it up. We'd likely only do it only if we detect no workspace. Second, even if we did that, we'd then detect more cases as being workspace members, exacerbating this.

Something I've considered is overloading pagkage.workspace (says where to find workspace) to also enable/disable workspace discovery. Defaulting that to false would get the benefits without the downsides.

[abmpicoli]

At first glance, I like the idea of having workspace discovery turned off by default. But this is a behavioral change that will affect existing projects.

So, if this is done, without breaking the build of all people using workspaces out there, this would demand a new cargo edition field version, right?

On the other hand, are there any people that are creating a complex project and creating blindly, say, 7 subprojects using cargo new without even looking into the cargo.toml? Projects tend to start small and then increase complexity and being reorganized into modules, multi-projects and then, "Bam!" Workspaces. People that are aware about workspaces and want to create a multi-project may simply remove the line in the recent cargo.toml file when creating new projects, or setting a local environment or central local configuration to do that, so they can change the behavior on how they generate new cargo artifacts, once.

In the book, people will be made aware early on that there is a "big thing called workspace, that for now you won't need, but check chapter X". There is no need to make complex explanations at that point: only that the '[workspace]' thing makes your project standalone.

One thing that people must be cautions always is the see-saw effect (people having to change configurations at either side manually to make things work, which may make people to change settings and breaking the other people repos on pull) , and the "it work at my machine" effect (some hidden setting at the user home or some parent directory changing how cargo build stuff).

package.workspace settings has all the smells of "it work at my machine" settings. While a new line when creating a new project is something that will be committed into the repo and can be removed (and committed) as part of the solution.

[epage]

At first glance, I like the idea of having workspace discovery turned off by default. But this is a behavioral change that will affect existing projects.

To be clear, I meant that by default cargo new would put package.workspace = false in a Cargo.toml if a workspace wans't found to make it a member of. This is fully within our compatibility guarantees.

On the other hand, are there any people that are creating a complex project and creating blindly, say, 7 subprojects using cargo new without even looking into the cargo.toml? Projects tend to start small and then increase complexity and being reorganized into modules, multi-projects and then, "Bam!" Workspaces. People that are aware about workspaces and want to create a multi-project may simply remove the line in the recent cargo.toml file when creating new projects, or setting a local environment or central local configuration to do that, so they can change the behavior on how they generate new cargo artifacts, once.

I want to re-emphasize: if we unconditionally put [workspace] (or package.workspace = false) in a package, we'd be removing features we recently added.

So that just leaves conditionally adding it. The question is if we'll cause more annoyance with [workspace] or package.workspace = false. I would posit the second because then the automatic workspace-handling we've added won't be unintentionally activated, requiring more than a single-line clean up.

[ehuss]

The cargo team discussed this and decided to close. Not all projects need (or want) a workspace, and there could be unwanted interactions with intentionally adding packages inside a workspace.

It sounds like some of the confusion here stems from diagnostics that did not explain what was happening or why. I think #13904 is the main issue for that.

Also, we did have some orthogonal desire to be able to have opt-in control the adding to a workspace with a CLI flag, but I think that is a separate concern (tracked in #8365).