Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(contrib): Point compilation docs to doc comments #11841

Merged
merged 1 commit into from
Mar 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/cargo/core/compiler/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
28 changes: 18 additions & 10 deletions src/cargo/ops/cargo_compile/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,27 +6,35 @@
//! 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
//! confused with target-triple or target architecture.
//!
//! [`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};
Expand Down
38 changes: 1 addition & 37 deletions src/doc/contrib/src/architecture/compilation.md
Original file line number Diff line number Diff line change
@@ -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)