docs(ref): Document MSRV-aware resolver

rust-lang · Oct 4, 2024 · 15f149e · 15f149e
1 parent 7975913
commit 15f149e
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 25 deletions.
diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
@@ -143,6 +143,9 @@ rpath = false            # Sets the rpath linking option.
 [profile.<name>.package.<name>]  # Override profile for a package.
 # Same keys for a normal profile (minus `panic`, `lto`, and `rpath`).
 
+[resolver]
+incompatible-rust-versions = "allow"  # Specifies how resolver reacts to these
+
 [registries.<name>]  # registries other than crates.io
 index = "…"          # URL of the registry index
 token = "…"          # authentication token for the registry
@@ -972,6 +975,28 @@ See [rpath](profiles.md#rpath).
 
 See [strip](profiles.md#strip).
 
+### `[resolver]`
+
+The `[resolver]` table overrides [dependency resolution behavior](resolver.md) for local development (e.g. excludes `cargo install`).
+
+#### `resolver.incompatible-rust-versions`
+* Type: string
+* Default: `"allow"`
+* Environment: `CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS`
+
+When resolving which version of a dependency to use, select how versions with incompatible `package.rust-version`s are treated.
+Values include:
+- `allow`: treat `rust-version`-incompatible versions like any other version
+- `fallback`: only consider `rust-version`-incompatible versions if no other version matched
+
+Can be overridden with
+- `--ignore-rust-version` CLI option
+- Setting the dependency's version requirement higher than any version with a compatible `rust-version`
+- Specifying the version to `cargo update` with `--precise`
+
+> **MSRV:**
+> - `allow` is supported on any version
+> - `fallback` is respected as of 1.83
 
 ### `[registries]`
 

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
@@ -350,31 +350,7 @@ This was stabilized in 1.79 in [#13608](https://github.com/rust-lang/cargo/pull/
 
 ### MSRV-aware resolver
 
-`-Zmsrv-policy` allows access to an MSRV-aware resolver which can be enabled with:
-- `resolver.incompatible-rust-versions` config field
-- `workspace.resolver = "3"` / `package.resolver = "3"`
-- `package.edition = "2024"` (only in workspace root)
-
-The resolver will prefer dependencies with a `package.rust-version` that is the same or older than your project's MSRV.
-As the resolver is unable to determine which workspace members will eventually
-depend on a package when it is being selected, we prioritize versions based on
-how many workspace member MSRVs they are compatible with.
-If there is no MSRV set then your toolchain version will be used, allowing it to pick up the toolchain version from pinned in rustup (e.g. `rust-toolchain.toml`).
-
-#### `resolver.incompatible-rust-versions`
-* Type: string
-* Default: `"allow"`
-* Environment: `CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS`
-
-When resolving a version for a dependency, select how versions with incompatible `package.rust-version`s are treated.
-Values include:
-- `allow`: treat `rust-version`-incompatible versions like any other version
-- `fallback`: only consider `rust-version`-incompatible versions if no other version matched
-
-Can be overridden with
-- `--ignore-rust-version` CLI option
-- Setting the dependency's version requirement higher than any version with a compatible `rust-version`
-- Specifying the version to `cargo update` with `--precise`
+This was stabilized in 1.83 in [#14639](https://github.com/rust-lang/cargo/pull/14639).
 
 ### Convert `incompatible_toolchain` error into a lint