cargo: More helpful error message when a stray `Cargo.toml` is present
Problem
Newcomers to Cargo occasionally end up with a Cargo.toml file that is irrelevant to the project they’re trying to run. (It is often in their home directory; perhaps they ran cargo init not understanding what it does, but that’s speculation.) When this happens, they get an error message that doesn’t really explain what is going on. An example from today:
$ cargo run
error: failed to parse manifest at '/home/user/Cargo.toml'
Caused by:
this virtual manifest specifies a 'dependencies' section, which is not allowed
New users don’t know what a “virtual manifest” is, and are dealing with too many new concepts already to notice that /home/user/Cargo.toml isn’t their project directory, nor do they know that it doesn’t make sense to have one there. (And this message doesn’t even contain the word “workspace”!)
Proposed Solution
Two parts:
-
When Cargo produces an error, the error is related to an invalid workspace manifest, and the purported workspace manifest path was found in a parent directory (rather than being the direct output of the
locate-projectalgorithm), produce a message which prints the paths of both manifests rather than only the workspace manifest, with some explanation that these are two different manifests and how each relates to the situation. -
If the purported workspace manifest is at least two levels up from the project manifest, or is located in the user’s home directory, produce an additional help message which speculates that the workspace manifest may be extraneous and should then be either deleted or relocated to avoid nesting unrelated projects.
Notes
@rustbot label +A-diagnostics +A-workspaces +E-easy
About this issue
- Original URL
- State: open
- Created 3 years ago
- Reactions: 10
- Comments: 16 (9 by maintainers)
Commits related to this issue
- fix(toml): Improve error on missing package and workspace That the error was confused was brought up in #13904 — committed to epage/cargo by epage 2 years ago
- Auto merge of #14261 - epage:error, r=weihanglo fix(toml): Improve error on missing package and workspace That the error was confused was brought up in #13904 — committed to rust-lang/cargo by bors 2 years ago
I’d enjoy something simple, like:
That moves away from the “workspace manifest” terminology while remaining helpful for more-experienced users.
If there is a way to add a
helpsection, and we can tell if there’s some issue with the package location, I’d like to see something similar to this:Also, if you do wish to continue using the manifest terminology, linking to the glossary may be neccessary: https://doc.rust-lang.org/cargo/appendix/glossary.html#manifest
In any case, if you have any advice for my input, please let me know! I’m looking to contribute more to Cargo and Rust in general. 😄
Instead of erroring on unused keys, Cargo warns. This is helpful when we are adding new functionality to
Cargo.tomlthat doesn’t otherwise require an MSRV bump, like adding[lints].A package must have at least
[package](or[project])[workspace]I can see improving the error if neither is present, rather than falling through to assuming its a virtual workspace.
I stumbled across this thread trying to fix the same problem but for a different reason. For some reason, I’d accidentally deleted a character of the ‘package’ TOML header so it read ‘packag’.
All fixed now, but I wanted to know why Cargo just blindly accepted
[packag]as a heading instead of throwing an error / warning about an unrecognised keyword.Furthermore, why does Cargo just assume it’s a virtual workspace just because the
[package]header is missing? Any answers are appreciated 😃