itsscb/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo.git synced 2025-09-28 11:20:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(resolver): Describe the role of the lockfile (#15958)

Browse Source 
### What does this PR try to resolve?

This fills a whole in our coverage of dependency resolution by
specifying how a `Cargo.lock` impacts it.

### How to test and review this PR?

I put it after version numbers and version requirements as it builds on
those two topics.

Unsure whether this fully resolves the concern from #15587 of users
coming from other ecosystems that have been burned by library lockfiles
affecting them to know that they won't be subject to that.
This commit is contained in:
Eric Huss 2025-09-12 17:37:10 +00:00 committed by GitHub
commit 506023fa54
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 26 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
src/doc/src/reference/resolver.md
View File

@ -3,11 +3,12 @@
One of Cargo's primary tasks is to determine the versions of dependencies to
use based on the version requirements specified in each package. This process
is called "dependency resolution" and is performed by the "resolver". The
result of the resolution is stored in the `Cargo.lock` file which "locks" the
result of the resolution is stored in the [`Cargo.lock` file] which "locks" the
dependencies to specific versions, and keeps them fixed over time.
The [`cargo tree`] command can be used to visualize the result of the
resolver.
[`Cargo.lock` file]: ../guide/cargo-toml-vs-cargo-lock.md
[dependency specifications]: specifying-dependencies.md
[dependency specification]: specifying-dependencies.md
[`cargo tree`]: ../commands/cargo-tree.md
@ -203,6 +204,30 @@ ecosystem if you publish a SemVer-incompatible version of a popular library.
[semver trick]: https://github.com/dtolnay/semver-trick
[`downcast_ref`]: ../../std/any/trait.Any.html#method.downcast_ref
### Lock file
Cargo gives the highest priority to versions contained in the [`Cargo.lock` file], when used.
This is intended to balance reproducible builds with adjusting to changes in the manifest.
For example, if you had a package in the resolve graph with:
```toml
[dependencies]
bitflags = "*"
```
If at the time your `Cargo.lock` file is generated, the greatest version of
`bitflags` is `1.2.1`, then the package will use `1.2.1` and recorded in the `Cargo.lock` file.
By the time Cargo next runs, `bitflags` `1.3.5` is out.
When resolving dependencies,
`1.2.1` will still be used because it is present in your `Cargo.lock` file.
The package is then edited to:
```toml
[dependencies]
bitflags = "1.3.0"
```
`bitflags` `1.2.1` does not match this version requirement and so that entry in your `Cargo.lock` file is ignored and version `1.3.5` will now be used and recorded in your `Cargo.lock` file.
### Rust version
To support developing software with a minimum supported [Rust version],