Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve workspace resolver error message when root edition is missing #13579

Closed
rimutaka opened this issue Mar 13, 2024 · 9 comments
Closed

Improve workspace resolver error message when root edition is missing #13579

rimutaka opened this issue Mar 13, 2024 · 9 comments
Labels
C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` S-needs-info Status: Needs more info, such as a reproduction or more background for a feature request.

Comments

@rimutaka
Copy link
Contributor

rimutaka commented Mar 13, 2024

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

@rimutaka rimutaka added C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` S-triage Status: This issue is waiting on initial triage. labels Mar 13, 2024
@rohansx
Copy link

rohansx commented Mar 13, 2024

@rimutaka would like to take on this tassk

@weihanglo
Copy link
Member

@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
Copy link
Member

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.

@weihanglo weihanglo added S-needs-info Status: Needs more info, such as a reproduction or more background for a feature request. and removed S-triage Status: This issue is waiting on initial triage. labels Mar 13, 2024
@rimutaka
Copy link
Contributor Author

rimutaka commented Mar 14, 2024

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:

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

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

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

image
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
Copy link
Member

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
Copy link
Member

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
Copy link
Contributor

epage commented Mar 14, 2024

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

@rimutaka
Copy link
Contributor Author

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

@weihanglo
Copy link
Member

Thanks. Closing.

@weihanglo weihanglo closed this as not planned Won't fix, can't repro, duplicate, stale Mar 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` S-needs-info Status: Needs more info, such as a reproduction or more background for a feature request.
Projects
None yet
Development

No branches or pull requests

4 participants