docs: add lock file section to the resolver docs #15587
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds some documentation about how lockfiles work to the resolver section, particularly regarding when lock files exist in library dependencies. Effectively re-adds an updated section of docs that was lost here: https://github.com/rust-lang/cargo/pull/12382/files#diff-197a732275c32bdbdb079bdd92ac8a4ba585ee556ea978e9e661804eb76ce9eeL117-L121 Related to this Zulip thread https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/cargo.20lock.20in.20dependency/with/519679182
rustbot
added
A-documenting-cargo-itself
weihanglo
reviewed
May 23, 2025
| @@ -12,6 +12,25 @@ resolver. | |||
| [dependency specification]: specifying-dependencies.md | |||
| [`cargo tree`]: ../commands/cargo-tree.md | |||
|
|
|||
| ## `Cargo.lock` lock-files | |||
|
|
|||
| The `Cargo.lock` file provides deterministic builds at different times and on | |||
There was a problem hiding this comment.
There are some other places the book mentions Cargo.lock
- https://doc.rust-lang.org/nightly/cargo/appendix/glossary.html
- https://doc.rust-lang.org/nightly/cargo/guide/cargo-toml-vs-cargo-lock.html#cargotoml-vs-cargolock
- https://doc.rust-lang.org/nightly/cargo/faq.html#why-have-cargolock-in-version-control
- The previous paragraph.
it is a bit duplicate everywhere. We might want some level of consolidation.
| Dependancy resolution is not run when cargo reads from `Cargo.lock`. | ||
|
|
||
| Not all cargo commands use `Cargo.lock` by default. Examples include | ||
| `cargo install` and `cargo update`.In these cases, `--locked` can usually be |
There was a problem hiding this comment.
This is a bit off. cargo update would always consult the existing Cargo.lock, especially when doing a partial update.
| The `Cargo.lock` file provides deterministic builds at different times and on | ||
| different systems, by ensuring that the exact same dependencies, versions, and | ||
| sources are used as when the `Cargo.lock` file was last generated. | ||
| Dependancy resolution is not run when cargo reads from `Cargo.lock`. |
There was a problem hiding this comment.
This is incorrect. Cargo always performs dependency resolutions and prefers to versions tracked in Cargo.lock.
| ### Libraries with `Cargo.lock` | ||
|
|
||
| Cargo treats `Cargo.lock` files differently when a crate is used as a library | ||
| dependency where an upper level `Cargo.lock` would exist. In these cases cargo will |
There was a problem hiding this comment.
Upper-level / top-level is pretty vague here. Cargo actually ignores any lockfile but the one at the workspace root.
There was a problem hiding this comment.
Perhaps instead, we can just talk about the property of a single view of dependency resolution, so that we don't repeat ourselves and still provide what you originally wanted to know.
### Single view of dependency resolution
When building a package or a workspace, Cargo computes a single,
unified resolution of all dependencies across the entire dependency graph.
This maximizes the reuse of package versions within the resolution process.
Unlike some other package managers, Cargo does not use Cargo.lock files
from dependencies or perform per-dependency resolution.
All resolution is done from the root.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds some documentation about how lockfiles work to the resolver section, particularly regarding when lock files exist in library dependencies.
Effectively re-adds an updated section of docs that was lost here: https://github.com/rust-lang/cargo/pull/12382/files#diff-197a732275c32bdbdb079bdd92ac8a4ba585ee556ea978e9e661804eb76ce9eeL117-L121
Related to this Zulip thread https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/cargo.20lock.20in.20dependency/with/519679182