refactor: separate "global" mode from CompileMode (#15601)

ehuss · web-flow · commit bffece899e9b · 2025-05-28T23:50:22.000Z
### What does this PR try to resolve?

This separates the concern of two different "mode".

- UserIntent: focus on the overall goal of the build
- CompileMode: the actual compile operation for each unit (I'd like to
rename it to something else in the future, such as CompileAction)

This is a preparation of adding `-Zno-link`/`-Zlink-only` support,
which we'll have `CompileMode::Link` but that doesn't make sense to
show up in `UserIntent`.

### How should we test and review this PR?

It should have no functional change.

### Additional information
diff --git a/src/bin/cargo/commands/bench.rs b/src/bin/cargo/commands/bench.rs
@@ -61,7 +61,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
     let ws = args.workspace(gctx)?;
 
     let mut compile_opts =
-        args.compile_options(gctx, CompileMode::Bench, Some(&ws), ProfileChecking::Custom)?;
+        args.compile_options(gctx, UserIntent::Bench, Some(&ws), ProfileChecking::Custom)?;
 
     compile_opts.build_config.requested_profile =
         args.get_profile_name("bench", ProfileChecking::Custom)?;
diff --git a/src/bin/cargo/commands/build.rs b/src/bin/cargo/commands/build.rs
@@ -49,7 +49,7 @@ pub fn cli() -> Command {
 pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
     let ws = args.workspace(gctx)?;
     let mut compile_opts =
-        args.compile_options(gctx, CompileMode::Build, Some(&ws), ProfileChecking::Custom)?;
+        args.compile_options(gctx, UserIntent::Build, Some(&ws), ProfileChecking::Custom)?;
 
     if let Some(artifact_dir) = args.value_of_path("artifact-dir", gctx) {
         // If the user specifies `--artifact-dir`, use that
diff --git a/src/bin/cargo/commands/check.rs b/src/bin/cargo/commands/check.rs
@@ -50,9 +50,9 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
         args.get_one::<String>("profile").map(String::as_str),
         Some("test")
     );
-    let mode = CompileMode::Check { test };
+    let intent = UserIntent::Check { test };
     let compile_opts =
-        args.compile_options(gctx, mode, Some(&ws), ProfileChecking::LegacyTestOnly)?;
+        args.compile_options(gctx, intent, Some(&ws), ProfileChecking::LegacyTestOnly)?;
 
     ops::compile(&ws, &compile_opts)?;
     Ok(())
diff --git a/src/bin/cargo/commands/doc.rs b/src/bin/cargo/commands/doc.rs
@@ -48,11 +48,12 @@ pub fn cli() -> Command {
 
 pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
     let ws = args.workspace(gctx)?;
-    let mode = CompileMode::Doc {
+    let intent = UserIntent::Doc {
         deps: !args.flag("no-deps"),
         json: false,
     };
-    let mut compile_opts = args.compile_options(gctx, mode, Some(&ws), ProfileChecking::Custom)?;
+    let mut compile_opts =
+        args.compile_options(gctx, intent, Some(&ws), ProfileChecking::Custom)?;
     compile_opts.rustdoc_document_private_items = args.flag("document-private-items");
 
     let doc_opts = DocOptions {
diff --git a/src/bin/cargo/commands/fix.rs b/src/bin/cargo/commands/fix.rs
@@ -67,7 +67,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
         args.get_one::<String>("profile").map(String::as_str),
         Some("test")
     );
-    let mode = CompileMode::Check { test };
+    let intent = UserIntent::Check { test };
 
     // Unlike other commands default `cargo fix` to all targets to fix as much
     // code as we can.
@@ -79,7 +79,8 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
     let lockfile_path = args.lockfile_path(gctx)?;
     ws.set_requested_lockfile_path(lockfile_path.clone());
 
-    let mut opts = args.compile_options(gctx, mode, Some(&ws), ProfileChecking::LegacyTestOnly)?;
+    let mut opts =
+        args.compile_options(gctx, intent, Some(&ws), ProfileChecking::LegacyTestOnly)?;
 
     let edition = args.flag("edition") || args.flag("edition-idioms");
     if !opts.filter.is_specific() && edition {
diff --git a/src/bin/cargo/commands/install.rs b/src/bin/cargo/commands/install.rs
@@ -216,7 +216,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
 
     let mut compile_opts = args.compile_options(
         gctx,
-        CompileMode::Build,
+        UserIntent::Build,
         workspace.as_ref(),
         ProfileChecking::Custom,
     )?;
diff --git a/src/bin/cargo/commands/run.rs b/src/bin/cargo/commands/run.rs
@@ -51,7 +51,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
     let ws = args.workspace(gctx)?;
 
     let mut compile_opts =
-        args.compile_options(gctx, CompileMode::Build, Some(&ws), ProfileChecking::Custom)?;
+        args.compile_options(gctx, UserIntent::Build, Some(&ws), ProfileChecking::Custom)?;
 
     // Disallow `spec` to be an glob pattern
     if let Packages::Packages(opt_in) = &compile_opts.spec {
@@ -180,7 +180,7 @@ pub fn exec_manifest_command(gctx: &mut GlobalContext, cmd: &str, args: &[OsStri
     }
 
     let mut compile_opts =
-        cargo::ops::CompileOptions::new(gctx, cargo::core::compiler::CompileMode::Build)?;
+        cargo::ops::CompileOptions::new(gctx, cargo::core::compiler::UserIntent::Build)?;
     compile_opts.spec = cargo::ops::Packages::Default;
 
     cargo::ops::run(&ws, &compile_opts, args).map_err(|err| to_run_error(gctx, err))
diff --git a/src/bin/cargo/commands/rustc.rs b/src/bin/cargo/commands/rustc.rs
@@ -64,15 +64,15 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
     // This is a legacy behavior that changes the behavior based on the profile.
     // If we want to support this more formally, I think adding a --mode flag
     // would be warranted.
-    let mode = match args.get_one::<String>("profile").map(String::as_str) {
-        Some("test") => CompileMode::Test,
-        Some("bench") => CompileMode::Bench,
-        Some("check") => CompileMode::Check { test: false },
-        _ => CompileMode::Build,
+    let intent = match args.get_one::<String>("profile").map(String::as_str) {
+        Some("test") => UserIntent::Test,
+        Some("bench") => UserIntent::Bench,
+        Some("check") => UserIntent::Check { test: false },
+        _ => UserIntent::Build,
     };
     let mut compile_opts = args.compile_options_for_single_package(
         gctx,
-        mode,
+        intent,
         Some(&ws),
         ProfileChecking::LegacyRustc,
     )?;
diff --git a/src/bin/cargo/commands/rustdoc.rs b/src/bin/cargo/commands/rustdoc.rs
@@ -64,7 +64,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
 
     let mut compile_opts = args.compile_options_for_single_package(
         gctx,
-        CompileMode::Doc {
+        UserIntent::Doc {
             deps: false,
             json: matches!(output_format, OutputFormat::Json),
         },
diff --git a/src/bin/cargo/commands/test.rs b/src/bin/cargo/commands/test.rs
@@ -72,7 +72,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
     let ws = args.workspace(gctx)?;
 
     let mut compile_opts =
-        args.compile_options(gctx, CompileMode::Test, Some(&ws), ProfileChecking::Custom)?;
+        args.compile_options(gctx, UserIntent::Test, Some(&ws), ProfileChecking::Custom)?;
 
     compile_opts.build_config.requested_profile =
         args.get_profile_name("test", ProfileChecking::Custom)?;
@@ -95,7 +95,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
         if no_run {
             return Err(anyhow::format_err!("Can't skip running doc tests with --no-run").into());
         }
-        compile_opts.build_config.mode = CompileMode::Doctest;
+        compile_opts.build_config.intent = UserIntent::Doctest;
         compile_opts.filter = ops::CompileFilter::lib_only();
     } else if test_name.is_some() && !compile_opts.filter.is_specific() {
         // If arg `TESTNAME` is provided, assumed that the user knows what
diff --git a/src/cargo/core/compiler/build_config.rs b/src/cargo/core/compiler/build_config.rs
@@ -21,8 +21,8 @@ pub struct BuildConfig {
     pub keep_going: bool,
     /// Build profile
     pub requested_profile: InternedString,
-    /// The mode we are compiling in.
-    pub mode: CompileMode,
+    /// The intent we are compiling in.
+    pub intent: UserIntent,
     /// `true` to print stdout in JSON format (for machine reading).
     pub message_format: MessageFormat,
     /// Force Cargo to do a full rebuild and treat each target as changed.
@@ -72,7 +72,7 @@ impl BuildConfig {
         jobs: Option<JobsConfig>,
         keep_going: bool,
         requested_targets: &[String],
-        mode: CompileMode,
+        intent: UserIntent,
     ) -> CargoResult<BuildConfig> {
         let cfg = gctx.build_config()?;
         let requested_kinds = CompileKind::from_requested_targets(gctx, requested_targets)?;
@@ -117,7 +117,7 @@ impl BuildConfig {
             jobs,
             keep_going,
             requested_profile: InternedString::new("dev"),
-            mode,
+            intent,
             message_format: MessageFormat::Human,
             force_rebuild: false,
             build_plan: false,
@@ -138,10 +138,6 @@ impl BuildConfig {
         matches!(self.message_format, MessageFormat::Json { .. })
     }
 
-    pub fn test(&self) -> bool {
-        self.mode == CompileMode::Test || self.mode == CompileMode::Bench
-    }
-
     pub fn single_requested_kind(&self) -> CargoResult<CompileKind> {
         match self.requested_kinds.len() {
             1 => Ok(self.requested_kinds[0]),
@@ -167,37 +163,28 @@ pub enum MessageFormat {
     Short,
 }
 
-/// The general "mode" for what to do.
-///
-/// This is used for two purposes. The commands themselves pass this in to
-/// `compile_ws` to tell it the general execution strategy. This influences
-/// the default targets selected. The other use is in the `Unit` struct
-/// to indicate what is being done with a specific target.
+/// The specific action to be performed on each `Unit` of work.
 #[derive(Clone, Copy, PartialEq, Debug, Eq, Hash, PartialOrd, Ord)]
 pub enum CompileMode {
-    /// A target being built for a test.
+    /// Test with `rustc`.
     Test,
-    /// Building a target with `rustc` (lib or bin).
+    /// Compile with `rustc`.
     Build,
-    /// Building a target with `rustc` to emit `rmeta` metadata only. If
-    /// `test` is true, then it is also compiled with `--test` to check it like
+    /// Type-check with `rustc` by emitting `rmeta` metadata only.
+    ///
+    /// If `test` is true, then it is also compiled with `--test` to check it like
     /// a test.
     Check { test: bool },
-    /// Used to indicate benchmarks should be built. This is not used in
-    /// `Unit`, because it is essentially the same as `Test` (indicating
-    /// `--test` should be passed to rustc) and by using `Test` instead it
-    /// allows some de-duping of Units to occur.
-    Bench,
-    /// A target that will be documented with `rustdoc`.
-
+    /// Document with `rustdoc`.
+    ///
     /// If `deps` is true, then it will also document all dependencies.
     /// if `json` is true, the documentation output is in json format.
     Doc { deps: bool, json: bool },
-    /// A target that will be tested with `rustdoc`.
+    /// Test with `rustdoc`.
     Doctest,
-    /// An example or library that will be scraped for function calls by `rustdoc`.
+    /// Scrape for function calls by `rustdoc`.
     Docscrape,
-    /// A marker for Units that represent the execution of a `build.rs` script.
+    /// Execute the binary built from the `build.rs` script.
     RunCustomBuild,
 }
 
@@ -211,7 +198,6 @@ impl ser::Serialize for CompileMode {
             Test => "test".serialize(s),
             Build => "build".serialize(s),
             Check { .. } => "check".serialize(s),
-            Bench => "bench".serialize(s),
             Doc { .. } => "doc".serialize(s),
             Doctest => "doctest".serialize(s),
             Docscrape => "docscrape".serialize(s),
@@ -246,19 +232,13 @@ impl CompileMode {
     pub fn is_any_test(self) -> bool {
         matches!(
             self,
-            CompileMode::Test
-                | CompileMode::Bench
-                | CompileMode::Check { test: true }
-                | CompileMode::Doctest
+            CompileMode::Test | CompileMode::Check { test: true } | CompileMode::Doctest
         )
     }
 
     /// Returns `true` if this is something that passes `--test` to rustc.
     pub fn is_rustc_test(self) -> bool {
-        matches!(
-            self,
-            CompileMode::Test | CompileMode::Bench | CompileMode::Check { test: true }
-        )
+        matches!(self, CompileMode::Test | CompileMode::Check { test: true })
     }
 
     /// Returns `true` if this is the *execution* of a `build.rs` script.
@@ -271,9 +251,64 @@ impl CompileMode {
     /// Note that this also returns `true` for building libraries, so you also
     /// have to check the target.
     pub fn generates_executable(self) -> bool {
+        matches!(self, CompileMode::Test | CompileMode::Build)
+    }
+}
+
+/// Represents the high-level operation requested by the user.
+///
+/// It determines which "Cargo targets" are selected by default and influences
+/// how they will be processed. This is derived from the Cargo command the user
+/// invoked (like `cargo build` or `cargo test`).
+///
+/// Unlike [`CompileMode`], which describes the specific compilation steps for
+/// individual units, [`UserIntent`] represents the overall goal of the build
+/// process as specified by the user.
+///
+/// For example, when a user runs `cargo test`, the intent is [`UserIntent::Test`],
+/// but this might result in multiple [`CompileMode`]s for different units.
+#[derive(Clone, Copy, Debug)]
+pub enum UserIntent {
+    /// Build benchmark binaries, e.g., `cargo bench`
+    Bench,
+    /// Build binaries and libraray, e.g., `cargo run`, `cargo install`, `cargo build`.
+    Build,
+    /// Perform type-check, e.g., `cargo check`.
+    Check { test: bool },
+    /// Document packages.
+    ///
+    /// If `deps` is true, then it will also document all dependencies.
+    /// if `json` is true, the documentation output is in json format.
+    Doc { deps: bool, json: bool },
+    /// Build doctest binaries, e.g., `cargo test --doc`
+    Doctest,
+    /// Build test binaries, e.g., `cargo test`
+    Test,
+}
+
+impl UserIntent {
+    /// Returns `true` if this is generating documentation.
+    pub fn is_doc(self) -> bool {
+        matches!(self, UserIntent::Doc { .. })
+    }
+
+    /// Returns `true` if this is any type of test (test, benchmark, doc test, or
+    /// check test).
+    pub fn is_any_test(self) -> bool {
+        matches!(
+            self,
+            UserIntent::Test
+                | UserIntent::Bench
+                | UserIntent::Check { test: true }
+                | UserIntent::Doctest
+        )
+    }
+
+    /// Returns `true` if this is something that passes `--test` to rustc.
+    pub fn is_rustc_test(self) -> bool {
         matches!(
             self,
-            CompileMode::Test | CompileMode::Bench | CompileMode::Build
+            UserIntent::Test | UserIntent::Bench | UserIntent::Check { test: true }
         )
     }
 }
diff --git a/src/cargo/core/compiler/build_context/target_info.rs b/src/cargo/core/compiler/build_context/target_info.rs
@@ -574,7 +574,7 @@ impl TargetInfo {
     ) -> CargoResult<(Vec<FileType>, Vec<CrateType>)> {
         match mode {
             CompileMode::Build => self.calc_rustc_outputs(target_kind, target_triple, gctx),
-            CompileMode::Test | CompileMode::Bench => {
+            CompileMode::Test => {
                 match self.file_types(&CrateType::Bin, FileFlavor::Normal, target_triple)? {
                     Some(fts) => Ok((fts, Vec::new())),
                     None => Ok((Vec::new(), vec![CrateType::Bin])),
diff --git a/src/cargo/core/compiler/build_runner/compilation_files.rs b/src/cargo/core/compiler/build_runner/compilation_files.rs
@@ -493,10 +493,7 @@ impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
                     flavor: FileFlavor::Normal,
                 }]
             }
-            CompileMode::Test
-            | CompileMode::Build
-            | CompileMode::Bench
-            | CompileMode::Check { .. } => {
+            CompileMode::Test | CompileMode::Build | CompileMode::Check { .. } => {
                 let mut outputs = self.calc_outputs_rustc(unit, bcx)?;
                 if bcx.build_config.sbom && bcx.gctx.cli_unstable().sbom {
                     let sbom_files: Vec<_> = outputs
diff --git a/src/cargo/core/compiler/build_runner/mod.rs b/src/cargo/core/compiler/build_runner/mod.rs
@@ -183,7 +183,7 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
         // any versioning (See https://github.com/rust-lang/cargo/issues/8461).
         // Therefore, we can end up with weird bugs and behaviours if we mix different
         // versions of these files.
-        if self.bcx.build_config.mode.is_doc() {
+        if self.bcx.build_config.intent.is_doc() {
             RustDocFingerprint::check_rustdoc_fingerprint(&self)?
         }
 
diff --git a/src/cargo/core/compiler/custom_build.rs b/src/cargo/core/compiler/custom_build.rs
@@ -28,16 +28,16 @@
 //! [build script]: https://doc.rust-lang.org/nightly/cargo/reference/build-scripts.html
 //! [`TargetKind::CustomBuild`]: crate::core::manifest::TargetKind::CustomBuild
 //! [`UnitGraph`]: super::unit_graph::UnitGraph
-//! [`CompileMode::RunCustomBuild`]: super::CompileMode
+//! [`CompileMode::RunCustomBuild`]: crate::core::compiler::CompileMode::RunCustomBuild
 //! [instructions]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script
 
 use super::{fingerprint, get_dynamic_search_path, BuildRunner, Job, Unit, Work};
 use crate::core::compiler::artifact;
 use crate::core::compiler::build_runner::UnitHash;
 use crate::core::compiler::fingerprint::DirtyReason;
 use crate::core::compiler::job_queue::JobState;
+use crate::core::compiler::CompileMode;
 use crate::core::{profiles::ProfileRoot, PackageId, Target};
-use crate::util::command_prelude::CompileMode;
 use crate::util::errors::CargoResult;
 use crate::util::internal;
 use crate::util::machine_message::{self, Message};
diff --git a/src/cargo/core/compiler/lto.rs b/src/cargo/core/compiler/lto.rs
@@ -97,7 +97,7 @@ fn calculate(
     let crate_types = match unit.mode {
         // Note: Doctest ignores LTO, but for now we'll compute it as-if it is
         // a Bin, in case it is ever supported in the future.
-        CompileMode::Test | CompileMode::Bench | CompileMode::Doctest => vec![CrateType::Bin],
+        CompileMode::Test | CompileMode::Doctest => vec![CrateType::Bin],
         // Notes on other modes:
         // - Check: Treat as the underlying type, it doesn't really matter.
         // - Doc: LTO is N/A for the Doc unit itself since rustdoc does not
diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs
@@ -69,6 +69,7 @@ use anyhow::{Context as _, Error};
 use lazycell::LazyCell;
 use tracing::{debug, instrument, trace};
 
+pub use self::build_config::UserIntent;
 pub use self::build_config::{BuildConfig, CompileMode, MessageFormat, TimingOutput};
 pub use self::build_context::{
     BuildContext, FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
diff --git a/src/cargo/core/compiler/timings.rs b/src/cargo/core/compiler/timings.rs
@@ -168,7 +168,6 @@ impl<'gctx> Timings<'gctx> {
             CompileMode::Build => {}
             CompileMode::Check { test: true } => target.push_str(" (check-test)"),
             CompileMode::Check { test: false } => target.push_str(" (check)"),
-            CompileMode::Bench => target.push_str(" (bench)"),
             CompileMode::Doc { .. } => target.push_str(" (doc)"),
             CompileMode::Doctest => target.push_str(" (doc test)"),
             CompileMode::Docscrape => target.push_str(" (doc scrape)"),
diff --git a/src/cargo/core/compiler/unit_dependencies.rs b/src/cargo/core/compiler/unit_dependencies.rs
diff --git a/src/cargo/ops/cargo_compile/compile_filter.rs b/src/cargo/ops/cargo_compile/compile_filter.rs
diff --git a/src/cargo/ops/cargo_compile/mod.rs b/src/cargo/ops/cargo_compile/mod.rs
diff --git a/src/cargo/ops/cargo_compile/unit_generator.rs b/src/cargo/ops/cargo_compile/unit_generator.rs
diff --git a/src/cargo/ops/cargo_fetch.rs b/src/cargo/ops/cargo_fetch.rs
diff --git a/src/cargo/ops/cargo_package/verify.rs b/src/cargo/ops/cargo_package/verify.rs
diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs
diff --git a/tests/testsuite/build.rs b/tests/testsuite/build.rs
diff --git a/tests/testsuite/member_errors.rs b/tests/testsuite/member_errors.rs
