Improve workspace resolver error message when root edition is missing

[rimutaka]

Problem

Running cargo new or cargo init within a workspace that has no edition tag in Cargo.toml works just fine, but returns a confusing error message about resolvers:

warning: virtual workspace defaulting to `resolver = "1"` despite one or more workspace members being on edition 2021 which implies `resolver = "2"`
note: to keep the current resolver, specify `workspace.resolver = "1"` in the workspace root's manifest
note: to use the edition 2021 resolver, specify `workspace.resolver = "2"` in the workspace root's manifest
note: for more details see https://doc.rust-lang.org/cargo/reference/resolver.html#resolver-versions

It took me some time to realise that the real problem was that I didn't have edition tag in the root manifest and it defaulted to 2015 while cargo new created a manifest with 2021.

This is not a biggie, but will probably trip up someone new to workspaces.

Proposed Solution

Add a note to suggest adding the missing edition tag to the root manifest. E.g.:

note: add missing `edition = "2021"` tag to [full path]/Cargo.toml 

Notes

Not sure how easy or practical this is or how often this situation occurs.
I ran into it by following instructions from an example in the Cargo book.
Feel free to close.

Relates to #10587

[rohansx]

@rimutaka would like to take on this tassk

[weihanglo]

@rohansx, the same, this is not triaged yet. (Sorry I have been consumed by day job these days)

If you wanna help out, you can look at how the issue tracker works in this repository. Specifically, issues with S-accepted are open for people to pick up.

Whenever you made up your mind picking up an issue, you could optionally add a comment @rustbot claim to assign the issue to yourself. See the doc for bot commands.

[weihanglo]

Not sure how easy or practical this is or how often this situation occurs.

I suspect it is pretty rare, as newer package will by default get edition key if created via cargo new. We also have #13505 which warns if edition key is missing, so I guess #13505 can mostly improve the situation here?

I ran into it by following instructions from an example in the Cargo book.

Which example is it? Maybe we can fix that example instead.

[rimutaka]

TLDR;

After writing all this I realise I was looking for an example how to create a workspace, found none, tried to piece together bits and pieces, failed. I'm not the brightest spark out there, so not sure how many others walk the same path :)

---

There is probably a dozen ways how it may happen, but here is my sequence of events:

• reading https://doc.rust-lang.org/cargo/reference/workspaces.html with the goal to quickly try how WSs work

Seems simple, but what do I put in # ...?

What's root package? I don't seem to need one. Skipping.

What's resolver? Why 2? I don't quite get it. Skipping.

This looks like what I need!

• created Cargo.toml in an empty root folder
• copy-pasted the above example into it
• ran cargo new foo
• stared at the error for some time trying to understand where I went wrong and what it all means
• looked at both Cargo.toml files and realised that I do not need the resolver as suggested - I have to specify the edition in the root

I think what tripped me up was the expectation that I do not have to have the root package table at all.

To create a workspace, you add the [workspace] table to a Cargo.toml:
At minimum, a workspace has to have a member, either with a root package or as a virtual manifest.
...
Alternatively, a Cargo.toml file can be created with a [workspace] section but without a [[package] section](https://doc.rust-lang.org/cargo/reference/manifest.html#the-package-section). 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.

I didn't want to use cargo new for the root because it doesn't have a workspace option and I wasn't sure if it's even appropriate for that. So I opted out for creating one manually.

---

There is a lot of info to take in on that page. All of it is well explained.

Maybe an example of how to create a WS using cargo commands would help. Relates to #11234 .

[weihanglo]

I see. This is more like a documentation issue than the resolver error message issue.

There are a couple of area to improve,

• Explain the behavior of a root package (or primary package or root mainfest, it has different names even in the source code 😓).
• Add resolver = 2 to every code block that people might simply copy over. This might be too much though.
• Add an example of, like your suggestion, creating a workspace step-by-stey

Alternatively, doing researches into #8365 or #5151 would also improve the current situation.

[weihanglo]

I think the original problem of this issue is resolved via #13505. We could keep this as a workspace doc enhancement request. Could you update the issue title and content?

[epage]

In general, we need to improve our "best practice" documentation though that is covered with issues like #11234.

[rimutaka]

@weihanglo , I reposted it as #13580. Feel free to close this one.

[weihanglo]

Thanks. Closing.