Merge remote-tracking branch 'upstream/master' into owner

* upstream/master:
  docs: fix typos in `cargo_compile/mod.rs`
  docs(contrib): Replace architecture with redirects
  docs(contrub): Remove unused file
  docs(contrib): Move some lower resolver details from ops to core
  docs(contrib): Move higher level resolver docs into doc comments
  docs(contrib): Pull impl info out of architecture

Author: heisen-li

src/cargo/core/resolver/mod.rs

@@ -37,6 +37,17 @@
 //! everything to bail out immediately and return success, and only if *nothing*
 //! works do we actually return an error up the stack.
 //!
+//! Resolution is currently performed twice
+//! 1. With all features enabled (this is what gets saved to `Cargo.lock`)
+//! 2. With only the specific features the user selected on the command-line. Ideally this
+//!    run will get removed in the future when transitioning to the new feature resolver.
+//!
+//! A new feature-specific resolver was added in 2020 which adds more sophisticated feature
+//! resolution. It is located in the [`features`] module. The original dependency resolver still
+//! performs feature unification, as it can help reduce the dependencies it has to consider during
+//! resolution (rather than assuming every optional dependency of every package is enabled).
+//! Checking if a feature is enabled must go through the new feature resolver.
+//!
 //! ## Performance
 //!
 //! Note that this is a relatively performance-critical portion of Cargo. The

src/cargo/lib.rs

@@ -31,8 +31,9 @@
 //!     This is the entry point for all the compilation commands. This is a
 //!     good place to start if you want to follow how compilation starts and
 //!     flows to completion.
-//! - [`core::resolver`]:
-//!   This is the dependency and feature resolvers.
+//! - [`ops::resolve`]:
+//!   Top-level API for dependency and feature resolver (e.g. [`ops::resolve_ws`])
+//!   - [`core::resolver`]: The core algorithm
 //! - [`core::compiler`]:
 //!   This is the code responsible for running `rustc` and `rustdoc`.
 //!   - [`core::compiler::build_context`]:

src/cargo/ops/cargo_compile/mod.rs

@@ -15,7 +15,7 @@
 //!   from the resolver.  See also [`unit_dependencies`].
 //! 5. Construct the [`BuildContext`] with all of the information collected so
 //!   far. This is the end of the "front end" of compilation.
-//! 6. Create a [`Context`] which oordinates the compilation process a
+//! 6. Create a [`Context`] which coordinates the compilation process
 //!   and will perform the following steps:
 //!     1. Prepare the `target` directory (see [`Layout`]).
 //!     2. Create a [`JobQueue`]. The queue checks the

src/cargo/ops/mod.rs

@@ -53,7 +53,7 @@ mod common_for_install_and_uninstall;
 mod fix;
 pub(crate) mod lockfile;
 pub(crate) mod registry;
-mod resolve;
+pub(crate) mod resolve;
 pub mod tree;
 mod vendor;
 

src/cargo/ops/resolve.rs

@@ -1,14 +1,59 @@
 //! High-level APIs for executing the resolver.
 //!
-//! This module provides functions for running the resolver given a workspace.
+//! This module provides functions for running the resolver given a workspace, including loading
+//! the `Cargo.lock` file and checkinf if it needs updating.
+//!
 //! There are roughly 3 main functions:
 //!
-//! - `resolve_ws`: A simple, high-level function with no options.
-//! - `resolve_ws_with_opts`: A medium-level function with options like
+//! - [`resolve_ws`]: A simple, high-level function with no options.
+//! - [`resolve_ws_with_opts`]: A medium-level function with options like
 //!   user-provided features. This is the most appropriate function to use in
 //!   most cases.
-//! - `resolve_with_previous`: A low-level function for running the resolver,
+//! - [`resolve_with_previous`]: A low-level function for running the resolver,
 //!   providing the most power and flexibility.
+//!
+//! ### Data Structures
+//!
+//! - [`Workspace`]:
+//!   Usually created by [`crate::util::command_prelude::ArgMatchesExt::workspace`] which discovers the root of the
+//!   workspace, and loads all the workspace members as a [`Package`] object
+//!   - [`Package`]
+//!     Corresponds with `Cargo.toml` manifest (deserialized as [`Manifest`]) and its associated files.
+//!     - [`Target`]s are crates such as the library, binaries, integration test, or examples.
+//!       They are what is actually compiled by `rustc`.
+//!       Each `Target` defines a crate root, like `src/lib.rs` or `examples/foo.rs`.
+//!     - [`PackageId`] --- A unique identifier for a package.
+//! - [`PackageRegistry`]:
+//!   The primary interface for how the dependency
+//!   resolver finds packages. It contains the `SourceMap`, and handles things
+//!   like the `[patch]` table. The dependency resolver
+//!   sends a query to the `PackageRegistry` to "get me all packages that match
+//!   this dependency declaration". The `Registry` trait provides a generic interface
+//!   to the `PackageRegistry`, but this is only used for providing an alternate
+//!   implementation of the `PackageRegistry` for testing.
+//! - [`SourceMap`]: Map of all available sources.
+//!   - [`Source`]: An abstraction for something that can fetch packages (a remote
+//!     registry, a git repo, the local filesystem, etc.). Check out the [source
+//!     implementations] for all the details about registries, indexes, git
+//!     dependencies, etc.
+//!       * [`SourceId`]: A unique identifier for a source.
+//!   - [`Summary`]: A of a [`Manifest`], and is essentially
+//!     the information that can be found in a registry index. Queries against the
+//!     `PackageRegistry` yields a `Summary`. The resolver uses the summary
+//!     information to build the dependency graph.
+//! - [`PackageSet`] --- Contains all of the `Package` objects. This works with the
+//!   [`Downloads`] struct to coordinate downloading packages. It has a reference
+//!   to the `SourceMap` to get the `Source` objects which tell the `Downloads`
+//!   struct which URLs to fetch.
+//!
+//! [`Package`]: crate::core::package
+//! [`Target`]: crate::core::Target
+//! [`Manifest`]: crate::core::Manifest
+//! [`Source`]: crate::core::Source
+//! [`SourceMap`]: crate::core::SourceMap
+//! [`PackageRegistry`]: crate::core::registry::PackageRegistry
+//! [source implementations]: crate::sources
+//! [`Downloads`]: crate::core::package::Downloads
 
 use crate::core::compiler::{CompileKind, RustcTargetData};
 use crate::core::registry::{LockedPatchDependency, PackageRegistry};

src/doc/contrib/book.toml

@@ -8,3 +8,10 @@ git-repository-url = "https://github.com/rust-lang/cargo/tree/master/src/doc/con
 
 [output.html.redirect]
 "/apidoc/cargo/index.html" = "https://doc.rust-lang.org/nightly/nightly-rustc/cargo/"
+"/architecture/index.html" = "../implementation/architecture.html"
+"/architecture/console.html" = "../implementation/console.html"
+"/architecture/subcommands.html" = "../implementation/subcommands.html"
+"/architecture/codebase.html" = "https://doc.rust-lang.org/nightly/nightly-rustc/cargo"
+"/architecture/compilation.html" = "https://doc.rust-lang.org/nightly/nightly-rustc/cargo"
+"/architecture/files.html" = "https://doc.rust-lang.org/nightly/nightly-rustc/cargo"
+"/architecture/packages.html" = "https://doc.rust-lang.org/nightly/nightly-rustc/cargo"

src/doc/contrib/src/SUMMARY.md

@@ -7,13 +7,12 @@
     - [Release process](./process/release.md)
     - [Unstable features](./process/unstable.md)
 - [Design Principles](./design.md)
-- [Architecture](./architecture/index.md)
-    - [Codebase Overview](./architecture/codebase.md)
-    - [SubCommands](./architecture/subcommands.md)
-    - [Console Output](./architecture/console.md)
-    - [Packages and Resolution](./architecture/packages.md)
-    - [Compilation](./architecture/compilation.md)
-    - [Files](./architecture/files.md)
+- [Implementing a Change](./implementation/index.md)
+    - [Architecture](./implementation/architecture.md)
+    - [New subcommands](./implementation/subcommands.md)
+    - [Console Output](./implementation/console.md)
+    - [Filesystem](./implementation/filesystem.md)
+    - [Debugging](./implementation/debugging.md)
 - [Tests](./tests/index.md)
     - [Running Tests](./tests/running.md)
     - [Writing Tests](./tests/writing.md)