Auto merge of #11241 - weihanglo:doc/build_context, r=epage

Polish docs for module `build_context`

Author: bors

src/cargo/core/compiler/build_context/mod.rs

@@ -1,3 +1,5 @@
+//! [`BuildContext`] is a (mostly) static information about a build task.
+
 use crate::core::compiler::unit_graph::UnitGraph;
 use crate::core::compiler::{BuildConfig, CompileKind, Unit};
 use crate::core::profiles::Profiles;
@@ -15,19 +17,42 @@ pub use self::target_info::{
     FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
 };
 
-/// The build context, containing all information about a build task.
+/// The build context, containing complete infomration needed for a build task
+/// before it gets started.
 ///
 /// It is intended that this is mostly static information. Stuff that mutates
-/// during the build can be found in the parent `Context`. (I say mostly,
+/// during the build can be found in the parent [`Context`]. (I say mostly,
 /// because this has internal caching, but nothing that should be observable
 /// or require &mut.)
+///
+/// As a result, almost every field on `BuildContext` is public, including
+///
+/// * a resolved [`UnitGraph`] of your dependencies,
+/// * a [`Profiles`] containing compiler flags presets,
+/// * a [`RustcTargetData`] containing host and target platform information,
+/// * and a [`PackageSet`] for further package downloads,
+///
+/// just to name a few. Learn more on each own documentation.
+///
+/// # How to use
+///
+/// To prepare a build task, you may not want to use [`BuildContext::new`] directly,
+/// since it is often too lower-level.
+/// Instead, [`ops::create_bcx`] is usually what you are looking for.
+///
+/// [`Context`]: crate::core::compiler::Context
+/// [`ops::create_bcx`]: crate::ops::create_bcx
 pub struct BuildContext<'a, 'cfg> {
     /// The workspace the build is for.
     pub ws: &'a Workspace<'cfg>,
 
     /// The cargo configuration.
     pub config: &'cfg Config,
+
+    /// This contains a collection of compiler flags presets.
     pub profiles: Profiles,
+
+    /// Configuration information for a rustc build.
     pub build_config: &'a BuildConfig,
 
     /// Extra compiler args for either `rustc` or `rustdoc`.
@@ -47,7 +72,7 @@ pub struct BuildContext<'a, 'cfg> {
     /// The dependency graph of units to compile.
     pub unit_graph: UnitGraph,
 
-    /// Reverse-dependencies of documented units, used by the rustdoc --scrape-examples flag.
+    /// Reverse-dependencies of documented units, used by the `rustdoc --scrape-examples` flag.
     pub scrape_units: Vec<Unit>,
 
     /// The list of all kinds that are involved in this build
@@ -88,6 +113,7 @@ impl<'a, 'cfg> BuildContext<'a, 'cfg> {
         })
     }
 
+    /// Information of the `rustc` this build task will use.
     pub fn rustc(&self) -> &Rustc {
         &self.target_data.rustc
     }
@@ -116,14 +142,36 @@ impl<'a, 'cfg> BuildContext<'a, 'cfg> {
         self.build_config.jobs
     }
 
+    /// Extra compiler flags to pass to `rustc` for a given unit.
+    ///
+    /// Although it depends on the caller, in the current Cargo implementation,
+    /// these flags take precendence over those from [`BuildContext::extra_args_for`].
+    ///
+    /// As of now, these flags come from environment variables and configurations.
+    /// See [`TargetInfo.rustflags`] for more on how Cargo collects them.
+    ///
+    /// [`TargetInfo.rustflags`]: TargetInfo::rustflags
     pub fn rustflags_args(&self, unit: &Unit) -> &[String] {
         &self.target_data.info(unit.kind).rustflags
     }
 
+    /// Extra compiler flags to pass to `rustdoc` for a given unit.
+    ///
+    /// Although it depends on the caller, in the current Cargo implementation,
+    /// these flags take precendence over those from [`BuildContext::extra_args_for`].
+    ///
+    /// As of now, these flags come from environment variables and configurations.
+    /// See [`TargetInfo.rustdocflags`] for more on how Cargo collects them.
+    ///
+    /// [`TargetInfo.rustdocflags`]: TargetInfo::rustdocflags
     pub fn rustdocflags_args(&self, unit: &Unit) -> &[String] {
         &self.target_data.info(unit.kind).rustdocflags
     }
 
+    /// Extra compiler args for either `rustc` or `rustdoc`.
+    ///
+    /// As of now, these flags come from the trailing args of either
+    /// `cargo rustc` or `cargo rustdoc`.
     pub fn extra_args_for(&self, unit: &Unit) -> Option<&Vec<String>> {
         self.extra_compiler_args.get(unit)
     }

src/cargo/core/compiler/build_context/target_info.rs

@@ -1,3 +1,12 @@
+//! This modules contains types storing information of target platfroms.
+//!
+//! Normally, call [`RustcTargetData::new`] to construct all the target
+//! platform once, and then query info on your demand. For example,
+//!
+//! * [`RustcTargetData::dep_platform_activated`] to check if platform is activated.
+//! * [`RustcTargetData::info`] to get a [`TargetInfo`] for an in-depth query.
+//! * [`TargetInfo::rustc_outputs`] to get a list of supported file types.
+
 use crate::core::compiler::{
     BuildOutput, CompileKind, CompileMode, CompileTarget, Context, CrateType,
 };
@@ -16,8 +25,9 @@ use std::str::{self, FromStr};
 
 /// Information about the platform target gleaned from querying rustc.
 ///
-/// `RustcTargetData` keeps two of these, one for the host and one for the
-/// target. If no target is specified, it uses a clone from the host.
+/// [`RustcTargetData`] keeps several of these, one for the host and the others
+/// for other specified targets. If no target is specified, it uses a clone from
+/// the host.
 #[derive(Clone)]
 pub struct TargetInfo {
     /// A base process builder for discovering crate type information. In
@@ -41,9 +51,9 @@ pub struct TargetInfo {
     /// Path to the "lib" directory in the sysroot which rustc uses for linking
     /// target libraries.
     pub sysroot_target_libdir: PathBuf,
-    /// Extra flags to pass to `rustc`, see `env_args`.
+    /// Extra flags to pass to `rustc`, see [`extra_args`].
     pub rustflags: Vec<String>,
-    /// Extra flags to pass to `rustdoc`, see `env_args`.
+    /// Extra flags to pass to `rustdoc`, see [`extra_args`].
     pub rustdocflags: Vec<String>,
     /// Whether or not rustc supports the `-Csplit-debuginfo` flag.
     pub supports_split_debuginfo: bool,
@@ -132,13 +142,20 @@ impl FileType {
 }
 
 impl TargetInfo {
+    /// Learns the information of target platform from `rustc` invocation(s).
+    ///
+    /// Generally, the first time calling this function is expensive, as it may
+    /// query `rustc` several times. To reduce the cost, output of each `rustc`
+    /// invocation is cached by [`Rustc::cached_output`].
+    ///
+    /// Search `Tricky` to learn why querying `rustc` several times is needed.
     pub fn new(
         config: &Config,
         requested_kinds: &[CompileKind],
         rustc: &Rustc,
         kind: CompileKind,
     ) -> CargoResult<TargetInfo> {
-        let mut rustflags = env_args(
+        let mut rustflags = extra_args(
             config,
             requested_kinds,
             &rustc.host,
@@ -149,6 +166,13 @@ impl TargetInfo {
         let mut turn = 0;
         loop {
             let extra_fingerprint = kind.fingerprint_hash();
+
+            // Query rustc for several kinds of info from each line of output:
+            // 0) file-names (to determine output file prefix/suffix for given crate type)
+            // 1) sysroot
+            // 2) cfg
+            //
+            // Search `--print` to see what we query so far.
             let mut process = rustc.workspace_process();
             process
                 .arg("-")
@@ -174,6 +198,8 @@ impl TargetInfo {
             for crate_type in KNOWN_CRATE_TYPES.iter() {
                 process.arg("--crate-type").arg(crate_type.as_str());
             }
+
+            // An extra `rustc` call to determine `-Csplit-debuginfo=packed` support.
             let supports_split_debuginfo = rustc
                 .cached_output(
                     process.clone().arg("-Csplit-debuginfo=packed"),
@@ -233,7 +259,7 @@ impl TargetInfo {
 
             // recalculate `rustflags` from above now that we have `cfg`
             // information
-            let new_flags = env_args(
+            let new_flags = extra_args(
                 config,
                 requested_kinds,
                 &rustc.host,
@@ -268,7 +294,7 @@ impl TargetInfo {
                 sysroot_host_libdir,
                 sysroot_target_libdir,
                 rustflags,
-                rustdocflags: env_args(
+                rustdocflags: extra_args(
                     config,
                     requested_kinds,
                     &rustc.host,
@@ -294,7 +320,7 @@ impl TargetInfo {
         true
     }
 
-    /// All the target `cfg` settings.
+    /// All the target [`Cfg`] settings.
     pub fn cfg(&self) -> &[Cfg] {
         &self.cfg
     }
@@ -580,6 +606,7 @@ fn output_err_info(cmd: &ProcessBuilder, stdout: &str, stderr: &str) -> String {
     result
 }
 
+/// Compiler flags for either rustc or rustdoc.
 #[derive(Debug, Copy, Clone)]
 enum Flags {
     Rust,
@@ -614,6 +641,7 @@ impl Flags {
 ///  - `target.*.rustflags` from the config (.cargo/config)
 ///  - `target.cfg(..).rustflags` from the config
 ///  - `host.*.rustflags` from the config if compiling a host artifact or without `--target`
+///     (requires `-Zhost-config`)
 ///
 /// then if none of those were found
 ///
@@ -624,7 +652,7 @@ impl Flags {
 /// For those artifacts, _only_ `host.*.rustflags` is respected, and no other configuration
 /// sources, _regardless of the value of `target-applies-to-host`_. This is counterintuitive, but
 /// necessary to retain backwards compatibility with older versions of Cargo.
-fn env_args(
+fn extra_args(
     config: &Config,
     requested_kinds: &[CompileKind],
     host_triple: &str,
@@ -669,6 +697,8 @@ fn env_args(
     }
 }
 
+/// Gets compiler flags from environment variables.
+/// See [`extra_args`] for more.
 fn rustflags_from_env(flags: Flags) -> Option<Vec<String>> {
     // First try CARGO_ENCODED_RUSTFLAGS from the environment.
     // Prefer this over RUSTFLAGS since it's less prone to encoding errors.
@@ -693,6 +723,8 @@ fn rustflags_from_env(flags: Flags) -> Option<Vec<String>> {
     None
 }
 
+/// Gets compiler flags from `[target]` section in the config.
+/// See [`extra_args`] for more.
 fn rustflags_from_target(
     config: &Config,
     host_triple: &str,
@@ -734,6 +766,8 @@ fn rustflags_from_target(
     }
 }
 
+/// Gets compiler flags from `[host]` section in the config.
+/// See [`extra_args`] for more.
 fn rustflags_from_host(
     config: &Config,
     flag: Flags,
@@ -750,6 +784,8 @@ fn rustflags_from_host(
     Ok(list.as_ref().map(|l| l.val.as_slice().to_vec()))
 }
 
+/// Gets compiler flags from `[build]` section in the config.
+/// See [`extra_args`] for more.
 fn rustflags_from_build(config: &Config, flag: Flags) -> CargoResult<Option<Vec<String>>> {
     // Then the `build.rustflags` value.
     let build = config.build_config()?;
@@ -773,11 +809,12 @@ pub struct RustcTargetData<'cfg> {
     /// `rustc` is invoked without a `--target` flag. This is used for
     /// procedural macros, build scripts, etc.
     host_config: TargetConfig,
+    /// Information about the host platform.
     host_info: TargetInfo,
 
-    /// Build information for targets that we're building for. This will be
-    /// empty if the `--target` flag is not passed.
+    /// Build information for targets that we're building for.
     target_config: HashMap<CompileTarget, TargetConfig>,
+    /// Information about the target platform that we're building for.
     target_info: HashMap<CompileTarget, TargetInfo>,
 }