Skip to content

Commit 4a2ebfb

Browse files
committed
Auto merge of #11604 - pkgw:resolver-unification-docs, r=ehuss
book: describe how the current resolver sometimes duplicates deps ### What does this PR try to resolve? This updates the book to document the behavior described in #9029, where sometimes Cargo will duplicate a dep when it doesn't have to. ### How should we test and review this PR? Doc-only change; someone with knowledge of the resolver should read and assess.
2 parents 04519ad + 50588a9 commit 4a2ebfb

File tree

1 file changed

+33
-2
lines changed

1 file changed

+33
-2
lines changed

src/doc/src/reference/resolver.md

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,10 @@ result of the resolution is stored in the `Cargo.lock` file which "locks" the
77
dependencies to specific versions, and keeps them fixed over time.
88

99
The resolver attempts to unify common dependencies while considering possibly
10-
conflicting requirements. The sections below provide some details on how these
11-
constraints are handled, and how to work with the resolver.
10+
conflicting requirements. It turns out, however, that in many cases there is no
11+
single "best" dependency resolution, and so the resolver must use heuristics to
12+
choose a preferred solution. The sections below provide some details on how
13+
requirements are handled, and how to work with the resolver.
1214

1315
See the chapter [Specifying Dependencies] for more details about how
1416
dependency requirements are specified.
@@ -490,6 +492,35 @@ break the build.
490492
The following illustrates some problems you may experience, and some possible
491493
solutions.
492494

495+
### Unexpected dependency duplication
496+
497+
The resolver algorithm may converge on a solution that includes two copies of a
498+
dependency when one would suffice. For example:
499+
500+
```toml
501+
# Package A
502+
[dependencies]
503+
rand = "0.7"
504+
505+
# Package B
506+
[dependencies]
507+
rand = ">=0.6" # note: open requirements such as this are discouraged
508+
```
509+
510+
In this example, Cargo may build two copies of the `rand` crate, even though a
511+
single copy at version `0.7.3` would meet all requirements. This is because the
512+
resolver's algorithm favors building the latest available version of `rand` for
513+
Package B, which is `0.8.5` at the time of this writing, and that is
514+
incompatible with Package A's specification. The resolver's algorithm does not
515+
currently attempt to "deduplicate" in this situation.
516+
517+
The use of open-ended version requirements like `>=0.6` is discouraged in Cargo.
518+
But, if you run into this situation, the [`cargo update`] command with the
519+
`--precise` flag can be used to manually remove such duplications.
520+
521+
[`cargo update`]: ../commands/cargo-update.md
522+
523+
493524
### SemVer-breaking patch release breaks the build
494525

495526
Sometimes a project may inadvertently publish a point release with a

0 commit comments

Comments
 (0)