Skip to content

Commit ef55037

Browse files
epageepage
committed
docs(contrib): Move higher level resolver docs into doc comments
I chose `ops::resolve` as the place for this as the docs cover the higher level details, including the `Cargo.lock` file, while `core::resolver` is more of the algorithm.
1 parent ed42a0d commit ef55037

File tree

4 files changed

+66
-97
lines changed

4 files changed

+66
-97
lines changed

‎src/cargo/lib.rs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,9 @@
3131
//! This is the entry point for all the compilation commands. This is a
3232
//! good place to start if you want to follow how compilation starts and
3333
//! flows to completion.
34-
//! - [`core::resolver`]:
35-
//! This is the dependency and feature resolvers.
34+
//! - [`ops::resolve`]:
35+
//! Top-level API for dependency and feature resolver (e.g. [`ops::resolve_ws`])
36+
//! - [`core::resolver`]: The core algorithm
3637
//! - [`core::compiler`]:
3738
//! This is the code responsible for running `rustc` and `rustdoc`.
3839
//! - [`core::compiler::build_context`]:

‎src/cargo/ops/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ mod common_for_install_and_uninstall;
5353
mod fix;
5454
pub(crate) mod lockfile;
5555
pub(crate) mod registry;
56-
mod resolve;
56+
pub(crate) mod resolve;
5757
pub mod tree;
5858
mod vendor;
5959

‎src/cargo/ops/resolve.rs‎

Lines changed: 61 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,71 @@
11
//! High-level APIs for executing the resolver.
22
//!
3-
//! This module provides functions for running the resolver given a workspace.
3+
//! This module provides functions for running the resolver given a workspace, including loading
4+
//! the `Cargo.lock` file and checkinf if it needs updating.
5+
//!
46
//! There are roughly 3 main functions:
57
//!
6-
//! - `resolve_ws`: A simple, high-level function with no options.
7-
//! - `resolve_ws_with_opts`: A medium-level function with options like
8+
//! - [`resolve_ws`]: A simple, high-level function with no options.
9+
//! - [`resolve_ws_with_opts`]: A medium-level function with options like
810
//! user-provided features. This is the most appropriate function to use in
911
//! most cases.
10-
//! - `resolve_with_previous`: A low-level function for running the resolver,
12+
//! - [`resolve_with_previous`]: A low-level function for running the resolver,
1113
//! providing the most power and flexibility.
14+
//!
15+
//! Resolution is currently performed twice
16+
//! 1. With all features enabled (this is what gets saved to `Cargo.lock`)
17+
//! 2. With only the specific features the user selected on the command-line. Ideally this
18+
//! run will get removed in the future when transitioning to the new feature resolver.
19+
//!
20+
//! A new feature-specific resolver was added in 2020 which adds more sophisticated feature
21+
//! resolution. It is located in the [`crate::core::resolver::features`] module. The original
22+
//! dependency resolver still performs feature unification, as it can help reduce the dependencies
23+
//! it has to consider during resolution (rather than assuming every optional dependency of every
24+
//! package is enabled). Checking if a feature is enabled must go through the new feature
25+
//! resolver.
26+
//!
27+
//! ### Data Structures
28+
//!
29+
//! - [`Workspace`]:
30+
//! Usually created by [`crate::util::command_prelude::ArgMatchesExt::workspace`] which discovers the root of the
31+
//! workspace, and loads all the workspace members as a [`Package`] object
32+
//! - [`Package`]
33+
//! Corresponds with `Cargo.toml` manifest (deserialized as [`Manifest`]) and its associated files.
34+
//! - [`Target`]s are crates such as the library, binaries, integration test, or examples.
35+
//! They are what is actually compiled by `rustc`.
36+
//! Each `Target` defines a crate root, like `src/lib.rs` or `examples/foo.rs`.
37+
//! - [`PackageId`] --- A unique identifier for a package.
38+
//! - [`PackageRegistry`]:
39+
//! The primary interface for how the dependency
40+
//! resolver finds packages. It contains the `SourceMap`, and handles things
41+
//! like the `[patch]` table. The dependency resolver
42+
//! sends a query to the `PackageRegistry` to "get me all packages that match
43+
//! this dependency declaration". The `Registry` trait provides a generic interface
44+
//! to the `PackageRegistry`, but this is only used for providing an alternate
45+
//! implementation of the `PackageRegistry` for testing.
46+
//! - [`SourceMap`]: Map of all available sources.
47+
//! - [`Source`]: An abstraction for something that can fetch packages (a remote
48+
//! registry, a git repo, the local filesystem, etc.). Check out the [source
49+
//! implementations] for all the details about registries, indexes, git
50+
//! dependencies, etc.
51+
//! * [`SourceId`]: A unique identifier for a source.
52+
//! - [`Summary`]: A of a [`Manifest`], and is essentially
53+
//! the information that can be found in a registry index. Queries against the
54+
//! `PackageRegistry` yields a `Summary`. The resolver uses the summary
55+
//! information to build the dependency graph.
56+
//! - [`PackageSet`] --- Contains all of the `Package` objects. This works with the
57+
//! [`Downloads`] struct to coordinate downloading packages. It has a reference
58+
//! to the `SourceMap` to get the `Source` objects which tell the `Downloads`
59+
//! struct which URLs to fetch.
60+
//!
61+
//! [`Package`]: crate::core::package
62+
//! [`Target`]: crate::core::Target
63+
//! [`Manifest`]: crate::core::Manifest
64+
//! [`Source`]: crate::core::Source
65+
//! [`SourceMap`]: crate::core::SourceMap
66+
//! [`PackageRegistry`]: crate::core::registry::PackageRegistry
67+
//! [source implementations]: crate::sources
68+
//! [`Downloads`]: crate::core::package::Downloads
1269
1370
use crate::core::compiler::{CompileKind, RustcTargetData};
1471
use crate::core::registry::{LockedPatchDependency, PackageRegistry};

‎src/doc/contrib/src/architecture/packages.md‎

Lines changed: 1 addition & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,3 @@
11
# Packages and Resolution
22

3-
## Workspaces
4-
5-
The [`Workspace`] object is usually created very early by calling the
6-
[`workspace`][ws-method] helper method. This discovers the root of the
7-
workspace, and loads all the workspace members as a [`Package`] object. Each
8-
package corresponds to a single `Cargo.toml` (which is deserialized into a
9-
[`Manifest`]), and may define several [`Target`]s, such as the library,
10-
binaries, integration test or examples. Targets are crates (each target
11-
defines a crate root, like `src/lib.rs` or `examples/foo.rs`) and are what is
12-
actually compiled by `rustc`.
13-
14-
## Packages and Sources
15-
16-
There are several data structures that are important to understand how
17-
packages are found and loaded:
18-
19-
* [`Package`] --- A package, which is a `Cargo.toml` manifest and its associated
20-
source files.
21-
* [`PackageId`] --- A unique identifier for a package.
22-
* [`Source`] --- An abstraction for something that can fetch packages (a remote
23-
registry, a git repo, the local filesystem, etc.). Check out the [source
24-
implementations] for all the details about registries, indexes, git
25-
dependencies, etc.
26-
* [`SourceId`] --- A unique identifier for a source.
27-
* [`SourceMap`] --- Map of all available sources.
28-
* [`PackageRegistry`] --- This is the main interface for how the dependency
29-
resolver finds packages. It contains the `SourceMap`, and handles things
30-
like the `[patch]` table. The `Registry` trait provides a generic interface
31-
to the `PackageRegistry`, but this is only used for providing an alternate
32-
implementation of the `PackageRegistry` for testing. The dependency resolver
33-
sends a query to the `PackageRegistry` to "get me all packages that match
34-
this dependency declaration".
35-
* [`Summary`] --- A summary is a subset of a [`Manifest`], and is essentially
36-
the information that can be found in a registry index. Queries against the
37-
`PackageRegistry` yields a `Summary`. The resolver uses the summary
38-
information to build the dependency graph.
39-
* [`PackageSet`] --- Contains all of the `Package` objects. This works with the
40-
[`Downloads`] struct to coordinate downloading packages. It has a reference
41-
to the `SourceMap` to get the `Source` objects which tell the `Downloads`
42-
struct which URLs to fetch.
43-
44-
All of these come together in the [`ops::resolve`] module. This module
45-
contains the primary functions for performing resolution (described below). It
46-
also handles downloading of packages. It is essentially where all of the data
47-
structures above come together.
48-
49-
## Resolver
50-
51-
[`Resolve`] is the representation of a directed graph of package dependencies,
52-
which uses [`PackageId`]s for nodes. This is the data structure that is saved
53-
to the `Cargo.lock` file. If there is no lock file, Cargo constructs a resolve
54-
by finding a graph of packages which matches declared dependency specification
55-
according to SemVer.
56-
57-
[`ops::resolve`] is the front-end for creating a `Resolve`. It handles loading
58-
the `Cargo.lock` file, checking if it needs updating, etc.
59-
60-
Resolution is currently performed twice. It is performed once with all
61-
features enabled. This is the resolve that gets saved to `Cargo.lock`. It then
62-
runs again with only the specific features the user selected on the
63-
command-line. Ideally this second run will get removed in the future when
64-
transitioning to the new feature resolver.
65-
66-
### Feature resolver
67-
68-
A new feature-specific resolver was added in 2020 which adds more
69-
sophisticated feature resolution. It is located in the [`resolver::features`]
70-
module. The original dependency resolver still performs feature unification,
71-
as it can help reduce the dependencies it has to consider during resolution
72-
(rather than assuming every optional dependency of every package is enabled).
73-
Checking if a feature is enabled must go through the new feature resolver.
74-
75-
76-
[`Workspace`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/workspace.rs
77-
[ws-method]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/command_prelude.rs#L298-L318
78-
[`Package`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/package.rs
79-
[`Target`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/manifest.rs#L181-L206
80-
[`Manifest`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/manifest.rs#L27-L51
81-
[`Source`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/source/mod.rs
82-
[`SourceId`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/source/source_id.rs
83-
[`SourceMap`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/source/mod.rs#L245-L249
84-
[`PackageRegistry`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/registry.rs#L36-L81
85-
[`ops::resolve`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/resolve.rs
86-
[`resolver::features`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/features.rs#L259
87-
[source implementations]: https://github.com/rust-lang/cargo/tree/master/src/cargo/sources
88-
[`PackageId`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/package_id.rs
89-
[`Summary`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/summary.rs
90-
[`PackageSet`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/package.rs#L283-L296
91-
[`Downloads`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/package.rs#L298-L352
92-
[`Resolve`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/resolve.rs
3+
See [nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/index.html)

0 commit comments

Comments
 (0)