diff --git a/src/cargo/core/compiler/build_context/mod.rs b/src/cargo/core/compiler/build_context/mod.rs index 5a8cc8d999e..f35084e2b7f 100644 --- a/src/cargo/core/compiler/build_context/mod.rs +++ b/src/cargo/core/compiler/build_context/mod.rs @@ -40,6 +40,8 @@ pub use self::target_info::{ /// since it is often too lower-level. /// Instead, [`ops::create_bcx`] is usually what you are looking for. /// +/// After a `BuildContext` is built, the next stage of building is handled in [`Context`]. +/// /// [`Context`]: crate::core::compiler::Context /// [`ops::create_bcx`]: crate::ops::create_bcx pub struct BuildContext<'a, 'cfg> { diff --git a/src/cargo/core/compiler/context/compilation_files.rs b/src/cargo/core/compiler/context/compilation_files.rs index dcfaabf327a..b025a6d53d4 100644 --- a/src/cargo/core/compiler/context/compilation_files.rs +++ b/src/cargo/core/compiler/context/compilation_files.rs @@ -1,3 +1,5 @@ +//! See [`CompilationFiles`]. + use std::collections::HashMap; use std::env; use std::fmt; @@ -16,7 +18,9 @@ use crate::util::{self, CargoResult, StableHasher}; /// This is a generic version number that can be changed to make /// backwards-incompatible changes to any file structures in the output /// directory. For example, the fingerprint files or the build-script -/// output files. Normally cargo updates ship with rustc updates which will +/// output files. +/// +/// Normally cargo updates ship with rustc updates which will /// cause a new hash due to the rustc version changing, but this allows /// cargo to be extra careful to deal with different versions of cargo that /// use the same rustc version. @@ -41,7 +45,7 @@ const METADATA_VERSION: u8 = 2; /// /// This also acts as the main layer of caching provided by Cargo. /// For example, we want to cache `cargo build` and `cargo doc` separately, so that running one -/// does not invalidate the artifacts for the other. We do this by including `CompileMode` in the +/// does not invalidate the artifacts for the other. We do this by including [`CompileMode`] in the /// hash, thus the artifacts go in different folders and do not override each other. /// If we don't add something that we should have, for this reason, we get the /// correct output but rebuild more than is needed. @@ -170,7 +174,9 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> { /// Gets the metadata for the given unit. /// - /// See module docs for more details. + /// See [`Metadata`] and [`fingerprint`] module for more. + /// + /// [`fingerprint`]: ../../fingerprint/index.html#fingerprints-and-metadata pub fn metadata(&self, unit: &Unit) -> Metadata { self.metas[unit].meta_hash } @@ -421,6 +427,9 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> { Some(uplift_path) } + /// Calculates the filenames that the given unit will generate. + /// Should use [`CompilationFiles::outputs`] instead + /// as it caches the result of this function. fn calc_outputs( &self, unit: &Unit, @@ -537,6 +546,11 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> { } } +/// Gets the metadata hash for the given [`Unit`]. +/// +/// Whne a metadata hash doesn't exist for the given unit, +/// this calls itself recursively to compute metadata hashes of all its dependencies. +/// See [`compute_metadata`] for how a single metadata hash is computed. fn metadata_of<'a>( unit: &Unit, cx: &Context<'_, '_>, @@ -552,6 +566,7 @@ fn metadata_of<'a>( &metas[unit] } +/// Computes the metadata hash for the given [`Unit`]. fn compute_metadata( unit: &Unit, cx: &Context<'_, '_>, @@ -632,6 +647,7 @@ fn compute_metadata( } } +/// Hash the version of rustc being used during the build process. fn hash_rustc_version(bcx: &BuildContext<'_, '_>, hasher: &mut StableHasher) { let vers = &bcx.rustc().version; if vers.pre.is_empty() || bcx.config.cli_unstable().separate_nightlies { diff --git a/src/cargo/core/compiler/context/mod.rs b/src/cargo/core/compiler/context/mod.rs index 08c86a5b6dd..dff61c2ed3f 100644 --- a/src/cargo/core/compiler/context/mod.rs +++ b/src/cargo/core/compiler/context/mod.rs @@ -1,3 +1,5 @@ +//! [`Context`] is the mutable state used during the build process. + use std::collections::{BTreeSet, HashMap, HashSet}; use std::path::{Path, PathBuf}; use std::sync::{Arc, Mutex}; @@ -27,6 +29,11 @@ use self::compilation_files::CompilationFiles; pub use self::compilation_files::{Metadata, OutputFile}; /// Collection of all the stuff that is needed to perform a build. +/// +/// Different from the [`BuildContext`], `Context` is a _mutable_ state used +/// throughout the entire build process. Everything is coordinated through this. +/// +/// [`BuildContext`]: crate::core::compiler::BuildContext pub struct Context<'a, 'cfg> { /// Mostly static information about the build task. pub bcx: &'a BuildContext<'a, 'cfg>, @@ -126,6 +133,10 @@ impl<'a, 'cfg> Context<'a, 'cfg> { /// Starts compilation, waits for it to finish, and returns information /// about the result of compilation. + /// + /// See [`ops::cargo_compile`] for a higher-level view of the compile process. + /// + /// [`ops::cargo_compile`]: ../../../ops/cargo_compile/index.html pub fn compile(mut self, exec: &Arc) -> CargoResult> { let mut queue = JobQueue::new(self.bcx); let mut plan = BuildPlan::new(); @@ -413,7 +424,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> { self.primary_packages.contains(&unit.pkg.package_id()) } - /// Returns the list of filenames read by cargo to generate the `BuildContext` + /// Returns the list of filenames read by cargo to generate the [`BuildContext`] /// (all `Cargo.toml`, etc.). pub fn build_plan_inputs(&self) -> CargoResult> { // Keep sorted for consistency. @@ -436,6 +447,8 @@ impl<'a, 'cfg> Context<'a, 'cfg> { } } + /// Check if any output file name collision happens. + /// See for more. fn check_collisions(&self) -> CargoResult<()> { let mut output_collisions = HashMap::new(); let describe_collision = |unit: &Unit, other_unit: &Unit, path: &PathBuf| -> String { @@ -608,6 +621,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> { self.rmeta_required.contains(unit) } + /// Used by `-Zjobserver-per-rustc`. pub fn new_jobserver(&mut self) -> CargoResult { let tokens = self.bcx.jobs() as usize; let client = Client::new(tokens).with_context(|| "failed to create jobserver")?;