From e14823174a3583d955ef4937947c668e58e4b27e Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 13 Mar 2023 13:21:44 -0500 Subject: [PATCH] docs(contrib): Point compilation docs to doc comments I also verified that `src/cargo/lib.rs` points people to this location for learning about compilation. --- src/cargo/core/compiler/mod.rs | 2 +- src/cargo/ops/cargo_compile/mod.rs | 28 +++++++++----- .../contrib/src/architecture/compilation.md | 38 +------------------ 3 files changed, 20 insertions(+), 48 deletions(-) diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs index 06dc0af009d..2699a2a216d 100644 --- a/src/cargo/core/compiler/mod.rs +++ b/src/cargo/core/compiler/mod.rs @@ -42,7 +42,7 @@ mod crate_type; mod custom_build; pub(crate) mod fingerprint; pub mod future_incompat; -mod job_queue; +pub(crate) mod job_queue; mod layout; mod links; mod lto; diff --git a/src/cargo/ops/cargo_compile/mod.rs b/src/cargo/ops/cargo_compile/mod.rs index 2113422b3ac..f4037c02da4 100644 --- a/src/cargo/ops/cargo_compile/mod.rs +++ b/src/cargo/ops/cargo_compile/mod.rs @@ -6,20 +6,26 @@ //! The [`compile`] function will do all the work to compile a workspace. A //! rough outline is: //! -//! - Resolve the dependency graph (see [`ops::resolve`]). -//! - Download any packages needed (see [`PackageSet`](crate::core::PackageSet)). -//! - Generate a list of top-level "units" of work for the targets the user +//! 1. Resolve the dependency graph (see [`ops::resolve`]). +//! 2. Download any packages needed (see [`PackageSet`](crate::core::PackageSet)). +//! 3. Generate a list of top-level "units" of work for the targets the user //! requested on the command-line. Each [`Unit`] corresponds to a compiler //! invocation. This is done in this module ([`UnitGenerator::generate_root_units`]). -//! - Build the graph of `Unit` dependencies (see [`unit_dependencies`]). -//! - Create a [`Context`] which will perform the following steps: -//! - Prepare the `target` directory (see [`Layout`]). -//! - Create a job queue (see `JobQueue`). The queue checks the +//! 4. Starting from the root [`Unit`]s, generate the [`UnitGraph`] by walking the dependency graph +//! 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 +//! and will perform the following steps: +//! 1. Prepare the `target` directory (see [`Layout`]). +//! 2. Create a [`JobQueue`]. The queue checks the //! fingerprint of each `Unit` to determine if it should run or be //! skipped. -//! - Execute the queue. Each leaf in the queue's dependency graph is -//! executed, and then removed from the graph when finished. This -//! repeats until the queue is empty. +//! 3. Execute the queue via [`drain_the_queue`]. Each leaf in the queue's dependency graph is +//! executed, and then removed from the graph when finished. This repeats until the queue is +//! empty. Note that this is the only point in cargo that currently uses threads. +//! 7. The result of the compilation is stored in the [`Compilation`] struct. This can be used for +//! various things, such as running tests after the compilation has finished. //! //! **Note**: "target" inside this module generally refers to ["Cargo Target"], //! which corresponds to artifact that will be built in a package. Not to be @@ -27,6 +33,8 @@ //! //! [`unit_dependencies`]: crate::core::compiler::unit_dependencies //! [`Layout`]: crate::core::compiler::Layout +//! [`JobQueue`]: crate::core::compiler::job_queue +//! [`drain_the_queue`]: crate::core::compiler::job_queue //! ["Cargo Target"]: https://doc.rust-lang.org/nightly/cargo/reference/cargo-targets.html use std::collections::{HashMap, HashSet}; diff --git a/src/doc/contrib/src/architecture/compilation.md b/src/doc/contrib/src/architecture/compilation.md index ecccee07152..37b22f6273c 100644 --- a/src/doc/contrib/src/architecture/compilation.md +++ b/src/doc/contrib/src/architecture/compilation.md @@ -1,39 +1,3 @@ # Compilation -The [`Unit`] is the primary data structure representing a single execution of -the compiler. It (mostly) contains all the information needed to determine -which flags to pass to the compiler. - -The entry to the compilation process is located in the [`cargo_compile`] -module. The compilation can be conceptually broken into these steps: - -1. Perform dependency resolution (see [the resolution chapter]). -2. Generate the root `Unit`s, the things the user requested to compile on the - command-line. This is done in the [`unit_generator`] module. -3. Starting from the root `Unit`s, generate the [`UnitGraph`] by walking the - dependency graph from the resolver. The `UnitGraph` contains all of the - `Unit` structs, and information about the dependency relationships between - units. This is done in the [`unit_dependencies`] module. -4. Construct the [`BuildContext`] with all of the information collected so - far. This is the end of the "front end" of compilation. -5. Create a [`Context`], a large, mutable data structure that coordinates the - compilation process. -6. The [`Context`] will create a [`JobQueue`], a data structure that tracks - which units need to be built. -7. [`drain_the_queue`] does the compilation process. This is the only point in - Cargo that currently uses threads. -8. The result of the compilation is stored in the [`Compilation`] struct. This - can be used for various things, such as running tests after the compilation - has finished. - -[`cargo_compile`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/mod.rs -[`unit_generator`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/unit_generator.rs -[`UnitGraph`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit_graph.rs -[the resolution chapter]: packages.md -[`Unit`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit.rs -[`unit_dependencies`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit_dependencies.rs -[`BuildContext`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/build_context/mod.rs -[`Context`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/context/mod.rs -[`JobQueue`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/job_queue.rs -[`drain_the_queue`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/compiler/job_queue.rs#L623-L634 -[`Compilation`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/compilation.rs +See [nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/ops/cargo_compile/index.html)