development/cargo
development/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo synced 2024-08-27 19:29:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Auto merge of #12388 - zvolin:docs-workspace-resolver, r=epage

Browse source 
docs: raise awareness of resolver used inside workspace

Workspaces by default use the resolver in version 1. It's been some time already since the 2021 edition which made version 2 a default for alone packages, but yet most of the projects that make a use of the workspaces still depends on  an old resolver.

By being explicit about the resolver tag inside the workspace we can lower the usage of older resolver for the new projects.

This can raise the awareness of this behavior and prevent issues like https://github.com/rust-lang/cargo/issues/12387. I also wasn't aware of this behavior before while not being so new to Rust, and we have the resolver 2 for good reasons, so I think we should be more explicit about it in the documentation.
When someone looks for the 'how to make cargo workspace' answers, he's unlikely to get to the `Dependency Resolution` section at the same time, he'll likely just copy paste the workspace example from the `Workspaces` and call it a day, yet extending the usage of an old resolver and not benefiting from the new one.
This commit is contained in:
bors 2023-07-26 15:29:49 +00:00
parent 54dfa98bbe ddfa20b208
commit 263d24baca
1 changed files with 8 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
src/doc/src/reference/workspaces.md
View file

@ -67,6 +67,7 @@ you want to keep all the packages organized in separate directories.
# [PROJECT_DIR]/Cargo.toml
[workspace]
members = ["hello_world"]
resolver = "2"
```
```toml
@ -74,9 +75,15 @@ members = ["hello_world"]
[package]
name = "hello_world" # the name of the package
version = "0.1.0" # the current version, obeying semver
edition = "2021" # the edition, will have no effect on a resolver used in the workspace
authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
```
Note that in a virtual manifest the [`resolver = "2"`](resolver.md#resolver-versions)
should be specified manually. It is usually deduced from the [`package.edition`][package-edition]
field which is absent in virtual manifests and the edition field of a member
won't affect the resolver used by the workspace.
### The `members` and `exclude` fields
The `members` and `exclude` fields define which packages are members of
@ -241,6 +248,7 @@ if that makes sense for the tool in question.
[package]: manifest.md#the-package-section
[`Cargo.lock`]: ../guide/cargo-toml-vs-cargo-lock.md
[package-metadata]: manifest.md#the-metadata-table
[package-edition]: manifest.md#the-edition-field
[output directory]: ../guide/build-cache.md
[patch]: overriding-dependencies.md#the-patch-section
[replace]: overriding-dependencies.md#the-replace-section