(Virtual?) manifest with both package and workspace sections is accepted

[sanmai-NL]

I created a new package using cargo new, then added the workspace section to the manifest. That did not work. When the manifest has both package and workspace sections, this is accepted by cargo and I found that confusing. Instead, cargo should report the manifest as invalid, since it apparently is.

BTW, once my error of having both sections was corrected to workspace-only, cargo reported:

is a virtual manifest, but this command requires running against an actual package in this workspace

I couldn't find a definition of ‘virtual manifest’ in the Cargo docs, however.

Version

cargo 0.17.0-nightly (40a4ce6 2017-01-06)

[alexcrichton]

Could you gist the manifest in question? This is actually intended behavior where a package can be the root of a workspace.

[kornelski]

I've ran into the intended behavior with this package: https://github.com/imazen/imageflow

"virtual manifest" is a term I haven't heard before, so the error message is not clear to me.

I hoped that by running cargo doc in the root I'm going to get a single unified documentation for all packages (all of their modules) in the workspace, so that I can browse around and see what each package does.

I suppose cargo doc --all is the closest equivalent of what I expected.

[behnam]

Virtual manifest is defined in the RFC:

A good number of projects do not necessarily have a "root Cargo.toml" which is an appropriate root for a workspace. To accommodate these projects and allow for the output of a workspace to be configured regardless of where crates are located, Cargo will now allow for "virtual manifest" files. These manifests will currently only contains the [workspace] table and will notably be lacking a [project] or [package] top level key.

Therefore, there's no package for the workspace root, therefore no cargo package or cargo publish for the root, but still the rest of the commands should work as expected, passing in the --all option.

By default, cargo always works on one single package (vs all packages in a workspace), therefore this is all expected behavior.

I think there's nothing left open in this issue and we can close it.

[alexcrichton]

Sounds good to me!

[sanmai-NL]

IMO concepts should be in user documentation, not only in an RFC. That issue remains.

I commented that a manifest with both package and workspace section is invalid. I do not immediately see how @behnam's comment changes this claim. That issue remains open as well then.

Please reopen the issue if this is true, @alexcrichton.

[behnam]

Valid point, @sanmai-NL. The online/current docs should contain the definition of Virtual Manifest and its behavior.

@alexcrichton, can we please reopen the issue to track the documentation matter? I can submit a PR, and take the assignment, if needed.

Also, @alexcrichton, it looks like that there's a lot of workspace-related content to go into the docs (this issue, #4304, and some other ones) What do you think about creating a separate page, like http://doc.crates.io/workspace.html, to cover all the details?