Improve documentation of the Rustc step and rename compiler to build_compiler in a few places

Author: Kobzol

src/bootstrap/src/core/build_steps/compile.rs

@@ -35,6 +35,7 @@ use crate::utils::helpers::{
 };
 use crate::{CLang, Compiler, DependencyType, FileType, GitRepo, LLVM_TOOLS, Mode, debug, trace};
 
+/// Build a standard library for the given `target` using the given `compiler`.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Std {
     pub target: TargetSelection,
@@ -960,11 +961,18 @@ fn cp_rustc_component_to_ci_sysroot(builder: &Builder<'_>, sysroot: &Path, conte
     }
 }
 
+/// Build rustc using the passed `build_compiler`.
+///
+/// - Makes sure that `build_compiler` has a standard library prepared for its host target,
+///   so that it can compile build scripts and proc macros when building this `rustc`.
+/// - Makes sure that `build_compiler` has a standard library prepared for `target`,
+///   so that the built `rustc` can *link to it* and use it at runtime.
 #[derive(Debug, PartialOrd, Ord, Clone, PartialEq, Eq, Hash)]
 pub struct Rustc {
+    /// The target on which rustc will run (its host).
     pub target: TargetSelection,
-    /// The **previous** compiler used to compile this compiler.
-    pub compiler: Compiler,
+    /// The **previous** compiler used to compile this rustc.
+    pub build_compiler: Compiler,
     /// Whether to build a subset of crates, rather than the whole compiler.
     ///
     /// This should only be requested by the user, not used within bootstrap itself.
@@ -974,8 +982,8 @@ pub struct Rustc {
 }
 
 impl Rustc {
-    pub fn new(compiler: Compiler, target: TargetSelection) -> Self {
-        Self { target, compiler, crates: Default::default() }
+    pub fn new(build_compiler: Compiler, target: TargetSelection) -> Self {
+        Self { target, build_compiler, crates: Default::default() }
     }
 }
 
@@ -1007,7 +1015,7 @@ impl Step for Rustc {
     fn make_run(run: RunConfig<'_>) {
         let crates = run.cargo_crates_in_set();
         run.builder.ensure(Rustc {
-            compiler: run
+            build_compiler: run
                 .builder
                 .compiler(run.builder.top_stage.saturating_sub(1), run.build_triple()),
             target: run.target,
@@ -1018,62 +1026,66 @@ impl Step for Rustc {
     /// Builds the compiler.
     ///
     /// This will build the compiler for a particular stage of the build using
-    /// the `compiler` targeting the `target` architecture. The artifacts
+    /// the `build_compiler` targeting the `target` architecture. The artifacts
     /// created will also be linked into the sysroot directory.
     #[cfg_attr(
         feature = "tracing",
         instrument(
             level = "debug",
             name = "Rustc::run",
             skip_all,
-            fields(previous_compiler = ?self.compiler, target = ?self.target),
+            fields(previous_compiler = ?self.build_compiler, target = ?self.target),
         ),
     )]
     fn run(self, builder: &Builder<'_>) -> u32 {
-        let compiler = self.compiler;
+        let build_compiler = self.build_compiler;
         let target = self.target;
 
         // NOTE: the ABI of the stage0 compiler is different from the ABI of the downloaded compiler,
         // so its artifacts can't be reused.
-        if builder.download_rustc() && compiler.stage != 0 {
-            trace!(stage = compiler.stage, "`download_rustc` requested");
+        if builder.download_rustc() && build_compiler.stage != 0 {
+            trace!(stage = build_compiler.stage, "`download_rustc` requested");
 
-            let sysroot = builder.ensure(Sysroot { compiler, force_recompile: false });
+            let sysroot =
+                builder.ensure(Sysroot { compiler: build_compiler, force_recompile: false });
             cp_rustc_component_to_ci_sysroot(
                 builder,
                 &sysroot,
                 builder.config.ci_rustc_dev_contents(),
             );
-            return compiler.stage;
+            return build_compiler.stage;
         }
 
-        builder.ensure(Std::new(compiler, target));
+        // Build a standard library for `target` using the `build_compiler`.
+        // This will be the standard library that the rustc which we build *links to*.
+        builder.ensure(Std::new(build_compiler, target));
 
-        if builder.config.keep_stage.contains(&compiler.stage) {
-            trace!(stage = compiler.stage, "`keep-stage` requested");
+        if builder.config.keep_stage.contains(&build_compiler.stage) {
+            trace!(stage = build_compiler.stage, "`keep-stage` requested");
 
             builder.info("WARNING: Using a potentially old librustc. This may not behave well.");
             builder.info("WARNING: Use `--keep-stage-std` if you want to rebuild the compiler when it changes");
-            builder.ensure(RustcLink::from_rustc(self, compiler));
+            builder.ensure(RustcLink::from_rustc(self, build_compiler));
 
-            return compiler.stage;
+            return build_compiler.stage;
         }
 
-        let compiler_to_use = builder.compiler_for(compiler.stage, compiler.host, target);
-        if compiler_to_use != compiler {
+        let compiler_to_use =
+            builder.compiler_for(build_compiler.stage, build_compiler.host, target);
+        if compiler_to_use != build_compiler {
             builder.ensure(Rustc::new(compiler_to_use, target));
             let msg = if compiler_to_use.host == target {
                 format!(
                     "Uplifting rustc (stage{} -> stage{})",
                     compiler_to_use.stage,
-                    compiler.stage + 1
+                    build_compiler.stage + 1
                 )
             } else {
                 format!(
                     "Uplifting rustc (stage{}:{} -> stage{}:{})",
                     compiler_to_use.stage,
                     compiler_to_use.host,
-                    compiler.stage + 1,
+                    build_compiler.stage + 1,
                     target
                 )
             };
@@ -1082,22 +1094,26 @@ impl Step for Rustc {
             return compiler_to_use.stage;
         }
 
-        // Ensure that build scripts and proc macros have a std / libproc_macro to link against.
+        // Build a standard library for the current host target using the `build_compiler`.
+        // This standard library will be used when building `rustc` for compiling
+        // build scripts and proc macros.
+        // If we are not cross-compiling, the Std build above will be the same one as the one we
+        // prepare here.
         builder.ensure(Std::new(
-            builder.compiler(self.compiler.stage, builder.config.host_target),
+            builder.compiler(self.build_compiler.stage, builder.config.host_target),
             builder.config.host_target,
         ));
 
         let mut cargo = builder::Cargo::new(
             builder,
-            compiler,
+            build_compiler,
             Mode::Rustc,
             SourceType::InTree,
             target,
             Kind::Build,
         );
 
-        rustc_cargo(builder, &mut cargo, target, &compiler, &self.crates);
+        rustc_cargo(builder, &mut cargo, target, &build_compiler, &self.crates);
 
         // NB: all RUSTFLAGS should be added to `rustc_cargo()` so they will be
         // consistently applied by check/doc/test modes too.
@@ -1106,19 +1122,19 @@ impl Step for Rustc {
             cargo.arg("-p").arg(krate);
         }
 
-        if builder.build.config.enable_bolt_settings && compiler.stage == 1 {
+        if builder.build.config.enable_bolt_settings && build_compiler.stage == 1 {
             // Relocations are required for BOLT to work.
             cargo.env("RUSTC_BOLT_LINK_FLAGS", "1");
         }
 
         let _guard = builder.msg_sysroot_tool(
             Kind::Build,
-            compiler.stage,
+            build_compiler.stage,
             format_args!("compiler artifacts{}", crate_description(&self.crates)),
-            compiler.host,
+            build_compiler.host,
             target,
         );
-        let stamp = build_stamp::librustc_stamp(builder, compiler, target);
+        let stamp = build_stamp::librustc_stamp(builder, build_compiler, target);
         run_cargo(
             builder,
             cargo,
@@ -1150,18 +1166,18 @@ impl Step for Rustc {
 
         builder.ensure(RustcLink::from_rustc(
             self,
-            builder.compiler(compiler.stage, builder.config.host_target),
+            builder.compiler(build_compiler.stage, builder.config.host_target),
         ));
 
-        compiler.stage
+        build_compiler.stage
     }
 }
 
 pub fn rustc_cargo(
     builder: &Builder<'_>,
     cargo: &mut Cargo,
     target: TargetSelection,
-    compiler: &Compiler,
+    build_compiler: &Compiler,
     crates: &[String],
 ) {
     cargo
@@ -1208,7 +1224,7 @@ pub fn rustc_cargo(
         cargo.rustflag("-Zdefault-visibility=protected");
     }
 
-    if is_lto_stage(compiler) {
+    if is_lto_stage(build_compiler) {
         match builder.config.rust_lto {
             RustcLto::Thin | RustcLto::Fat => {
                 // Since using LTO for optimizing dylibs is currently experimental,
@@ -1241,15 +1257,15 @@ pub fn rustc_cargo(
     // is already on by default in MSVC optimized builds, which is interpreted as --icf=all:
     // https://github.com/llvm/llvm-project/blob/3329cec2f79185bafd678f310fafadba2a8c76d2/lld/COFF/Driver.cpp#L1746
     // https://github.com/rust-lang/rust/blob/f22819bcce4abaff7d1246a56eec493418f9f4ee/compiler/rustc_codegen_ssa/src/back/linker.rs#L827
-    if builder.config.lld_mode.is_used() && !compiler.host.is_msvc() {
+    if builder.config.lld_mode.is_used() && !build_compiler.host.is_msvc() {
         cargo.rustflag("-Clink-args=-Wl,--icf=all");
     }
 
     if builder.config.rust_profile_use.is_some() && builder.config.rust_profile_generate.is_some() {
         panic!("Cannot use and generate PGO profiles at the same time");
     }
     let is_collecting = if let Some(path) = &builder.config.rust_profile_generate {
-        if compiler.stage == 1 {
+        if build_compiler.stage == 1 {
             cargo.rustflag(&format!("-Cprofile-generate={path}"));
             // Apparently necessary to avoid overflowing the counters during
             // a Cargo build profile
@@ -1259,7 +1275,7 @@ pub fn rustc_cargo(
             false
         }
     } else if let Some(path) = &builder.config.rust_profile_use {
-        if compiler.stage == 1 {
+        if build_compiler.stage == 1 {
             cargo.rustflag(&format!("-Cprofile-use={path}"));
             if builder.is_verbose() {
                 cargo.rustflag("-Cllvm-args=-pgo-warn-missing-function");
@@ -1284,20 +1300,20 @@ pub fn rustc_cargo(
     // useful.
     // This is only performed for non-incremental builds, as ccache cannot deal with these.
     if let Some(ref ccache) = builder.config.ccache
-        && compiler.stage == 0
+        && build_compiler.stage == 0
         && !builder.config.incremental
     {
         cargo.env("RUSTC_WRAPPER", ccache);
     }
 
-    rustc_cargo_env(builder, cargo, target, compiler.stage);
+    rustc_cargo_env(builder, cargo, target, build_compiler.stage);
 }
 
 pub fn rustc_cargo_env(
     builder: &Builder<'_>,
     cargo: &mut Cargo,
     target: TargetSelection,
-    stage: u32,
+    build_stage: u32,
 ) {
     // Set some configuration variables picked up by build scripts and
     // the compiler alike
@@ -1364,7 +1380,7 @@ pub fn rustc_cargo_env(
             crate::core::build_steps::llvm::prebuilt_llvm_config(builder, target, false)
                 .should_build();
         // `top_stage == stage` might be false for `check --stage 1`, if we are building the stage 1 compiler
-        let can_skip_build = builder.kind == Kind::Check && builder.top_stage == stage;
+        let can_skip_build = builder.kind == Kind::Check && builder.top_stage == build_stage;
         let should_skip_build = building_is_expensive && can_skip_build;
         if !should_skip_build {
             rustc_llvm_env(builder, cargo, target)
@@ -1475,7 +1491,7 @@ impl RustcLink {
     fn from_rustc(rustc: Rustc, host_compiler: Compiler) -> Self {
         Self {
             compiler: host_compiler,
-            previous_stage_compiler: rustc.compiler,
+            previous_stage_compiler: rustc.build_compiler,
             target: rustc.target,
             crates: rustc.crates,
         }