From 006023c5827b2288230df51676b69b725b822e86 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 10 Aug 2020 17:35:34 -0700 Subject: [PATCH] Update from review comments. --- src/doc/src/reference/resolver.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/src/doc/src/reference/resolver.md b/src/doc/src/reference/resolver.md index ba82659afa9..029f6b90e79 100644 --- a/src/doc/src/reference/resolver.md +++ b/src/doc/src/reference/resolver.md @@ -213,7 +213,10 @@ the [`perf` feature], then the oldest version it can select is `1.3.0`, because versions prior to that did not contain the `perf` feature. Similarly, if a feature is removed from a new release, then packages that require that feature will be stuck on the older releases that contain that feature. It is -discouraged to remove features in a SemVer-compatible release. +discouraged to remove features in a SemVer-compatible release. Beware that +optional dependencies also define an implicit feature, so removing an optional +dependency or making it non-optional can cause problems, see [removing an +optional dependency]. [`im`]: https://crates.io/crates/im [`perf` feature]: https://github.com/rust-lang/regex/blob/1.3.0/Cargo.toml#L56 @@ -221,17 +224,20 @@ discouraged to remove features in a SemVer-compatible release. [`regex`]: https://crates.io/crates/regex [`serde` dependency]: https://github.com/bodil/im-rs/blob/v15.0.0/Cargo.toml#L46 [features]: features.md +[removing an optional dependency]: semver.md#cargo-remove-opt-dep [workspace]: workspaces.md ### `links` The [`links` field] is used to ensure only one copy of a native library is -linked into a binary. It is an error if multiple SemVer-incompatible versions -of a package with a `links` field appears in the resolve graph. For example, -it is an error if one package depends on [`libgit2-sys`] version `0.11` and -another depends on `0.12`, because Cargo is unable to unify those, but they -both link to the `git2` native library. Due to this rigid requirement, it is -encouraged to be very careful when making SemVer-incompatible releases with +linked into a binary. The resolver will attempt to find a graph where there is +only one instance of each `links` name. If it is unable to find a graph that +satisfies that constraint, it will return an error. + +For example, it is an error if one package depends on [`libgit2-sys`] version +`0.11` and another depends on `0.12`, because Cargo is unable to unify those, +but they both link to the `git2` native library. Due to this requirement, it +is encouraged to be very careful when making SemVer-incompatible releases with the `links` field if your library is in common use. [`links` field]: manifest.md#the-links-field