cargo/core/compiler/
build_config.rs

1use crate::core::compiler::CompileKind;
2use crate::util::context::JobsConfig;
3use crate::util::interning::InternedString;
4use crate::util::{CargoResult, GlobalContext, RustfixDiagnosticServer};
5use anyhow::{bail, Context as _};
6use cargo_util::ProcessBuilder;
7use serde::ser;
8use std::cell::RefCell;
9use std::path::PathBuf;
10use std::rc::Rc;
11use std::thread::available_parallelism;
12
13/// Configuration information for a rustc build.
14#[derive(Debug, Clone)]
15pub struct BuildConfig {
16    /// The requested kind of compilation for this session
17    pub requested_kinds: Vec<CompileKind>,
18    /// Number of rustc jobs to run in parallel.
19    pub jobs: u32,
20    /// Do not abort the build as soon as there is an error.
21    pub keep_going: bool,
22    /// Build profile
23    pub requested_profile: InternedString,
24    /// The intent we are compiling in.
25    pub intent: UserIntent,
26    /// `true` to print stdout in JSON format (for machine reading).
27    pub message_format: MessageFormat,
28    /// Force Cargo to do a full rebuild and treat each target as changed.
29    pub force_rebuild: bool,
30    /// Output a build plan to stdout instead of actually compiling.
31    pub build_plan: bool,
32    /// Output the unit graph to stdout instead of actually compiling.
33    pub unit_graph: bool,
34    /// `true` to avoid really compiling.
35    pub dry_run: bool,
36    /// An optional override of the rustc process for primary units
37    pub primary_unit_rustc: Option<ProcessBuilder>,
38    /// A thread used by `cargo fix` to receive messages on a socket regarding
39    /// the success/failure of applying fixes.
40    pub rustfix_diagnostic_server: Rc<RefCell<Option<RustfixDiagnosticServer>>>,
41    /// The directory to copy final artifacts to. Note that even if
42    /// `artifact-dir` is set, a copy of artifacts still can be found at
43    /// `target/(debug\release)` as usual.
44    /// Named `export_dir` to avoid confusion with
45    /// `CompilationFiles::artifact_dir`.
46    pub export_dir: Option<PathBuf>,
47    /// `true` to output a future incompatibility report at the end of the build
48    pub future_incompat_report: bool,
49    /// Which kinds of build timings to output (empty if none).
50    pub timing_outputs: Vec<TimingOutput>,
51    /// Output SBOM precursor files.
52    pub sbom: bool,
53    /// Build compile time dependencies only, e.g., build scripts and proc macros
54    pub compile_time_deps_only: bool,
55}
56
57fn default_parallelism() -> CargoResult<u32> {
58    Ok(available_parallelism()
59        .context("failed to determine the amount of parallelism available")?
60        .get() as u32)
61}
62
63impl BuildConfig {
64    /// Parses all config files to learn about build configuration. Currently
65    /// configured options are:
66    ///
67    /// * `build.jobs`
68    /// * `build.target`
69    /// * `target.$target.ar`
70    /// * `target.$target.linker`
71    /// * `target.$target.libfoo.metadata`
72    pub fn new(
73        gctx: &GlobalContext,
74        jobs: Option<JobsConfig>,
75        keep_going: bool,
76        requested_targets: &[String],
77        intent: UserIntent,
78    ) -> CargoResult<BuildConfig> {
79        let cfg = gctx.build_config()?;
80        let requested_kinds = CompileKind::from_requested_targets(gctx, requested_targets)?;
81        if jobs.is_some() && gctx.jobserver_from_env().is_some() {
82            gctx.shell().warn(
83                "a `-j` argument was passed to Cargo but Cargo is \
84                 also configured with an external jobserver in \
85                 its environment, ignoring the `-j` parameter",
86            )?;
87        }
88        let jobs = match jobs.or(cfg.jobs.clone()) {
89            None => default_parallelism()?,
90            Some(value) => match value {
91                JobsConfig::Integer(j) => match j {
92                    0 => anyhow::bail!("jobs may not be 0"),
93                    j if j < 0 => (default_parallelism()? as i32 + j).max(1) as u32,
94                    j => j as u32,
95                },
96                JobsConfig::String(j) => match j.as_str() {
97                    "default" => default_parallelism()?,
98                    _ => {
99                        anyhow::bail!(
100			    format!("could not parse `{j}`. Number of parallel jobs should be `default` or a number."))
101                    }
102                },
103            },
104        };
105
106        // If sbom flag is set, it requires the unstable feature
107        let sbom = match (cfg.sbom, gctx.cli_unstable().sbom) {
108            (Some(sbom), true) => sbom,
109            (Some(_), false) => {
110                gctx.shell()
111                    .warn("ignoring 'sbom' config, pass `-Zsbom` to enable it")?;
112                false
113            }
114            (None, _) => false,
115        };
116
117        Ok(BuildConfig {
118            requested_kinds,
119            jobs,
120            keep_going,
121            requested_profile: "dev".into(),
122            intent,
123            message_format: MessageFormat::Human,
124            force_rebuild: false,
125            build_plan: false,
126            unit_graph: false,
127            dry_run: false,
128            primary_unit_rustc: None,
129            rustfix_diagnostic_server: Rc::new(RefCell::new(None)),
130            export_dir: None,
131            future_incompat_report: false,
132            timing_outputs: Vec::new(),
133            sbom,
134            compile_time_deps_only: false,
135        })
136    }
137
138    /// Whether or not the *user* wants JSON output. Whether or not rustc
139    /// actually uses JSON is decided in `add_error_format`.
140    pub fn emit_json(&self) -> bool {
141        matches!(self.message_format, MessageFormat::Json { .. })
142    }
143
144    pub fn single_requested_kind(&self) -> CargoResult<CompileKind> {
145        match self.requested_kinds.len() {
146            1 => Ok(self.requested_kinds[0]),
147            _ => bail!("only one `--target` argument is supported"),
148        }
149    }
150}
151
152#[derive(Clone, Copy, Debug, PartialEq, Eq)]
153pub enum MessageFormat {
154    Human,
155    Json {
156        /// Whether rustc diagnostics are rendered by cargo or included into the
157        /// output stream.
158        render_diagnostics: bool,
159        /// Whether the `rendered` field of rustc diagnostics are using the
160        /// "short" rendering.
161        short: bool,
162        /// Whether the `rendered` field of rustc diagnostics embed ansi color
163        /// codes.
164        ansi: bool,
165    },
166    Short,
167}
168
169/// The specific action to be performed on each `Unit` of work.
170#[derive(Clone, Copy, PartialEq, Debug, Eq, Hash, PartialOrd, Ord)]
171pub enum CompileMode {
172    /// Test with `rustc`.
173    Test,
174    /// Compile with `rustc`.
175    Build,
176    /// Type-check with `rustc` by emitting `rmeta` metadata only.
177    ///
178    /// If `test` is true, then it is also compiled with `--test` to check it like
179    /// a test.
180    Check { test: bool },
181    /// Document with `rustdoc`.
182    Doc,
183    /// Test with `rustdoc`.
184    Doctest,
185    /// Scrape for function calls by `rustdoc`.
186    Docscrape,
187    /// Execute the binary built from the `build.rs` script.
188    RunCustomBuild,
189}
190
191impl ser::Serialize for CompileMode {
192    fn serialize<S>(&self, s: S) -> Result<S::Ok, S::Error>
193    where
194        S: ser::Serializer,
195    {
196        use self::CompileMode::*;
197        match *self {
198            Test => "test".serialize(s),
199            Build => "build".serialize(s),
200            Check { .. } => "check".serialize(s),
201            Doc { .. } => "doc".serialize(s),
202            Doctest => "doctest".serialize(s),
203            Docscrape => "docscrape".serialize(s),
204            RunCustomBuild => "run-custom-build".serialize(s),
205        }
206    }
207}
208
209impl CompileMode {
210    /// Returns `true` if the unit is being checked.
211    pub fn is_check(self) -> bool {
212        matches!(self, CompileMode::Check { .. })
213    }
214
215    /// Returns `true` if this is generating documentation.
216    pub fn is_doc(self) -> bool {
217        matches!(self, CompileMode::Doc { .. })
218    }
219
220    /// Returns `true` if this a doc test.
221    pub fn is_doc_test(self) -> bool {
222        self == CompileMode::Doctest
223    }
224
225    /// Returns `true` if this is scraping examples for documentation.
226    pub fn is_doc_scrape(self) -> bool {
227        self == CompileMode::Docscrape
228    }
229
230    /// Returns `true` if this is any type of test (test, benchmark, doc test, or
231    /// check test).
232    pub fn is_any_test(self) -> bool {
233        matches!(
234            self,
235            CompileMode::Test | CompileMode::Check { test: true } | CompileMode::Doctest
236        )
237    }
238
239    /// Returns `true` if this is something that passes `--test` to rustc.
240    pub fn is_rustc_test(self) -> bool {
241        matches!(self, CompileMode::Test | CompileMode::Check { test: true })
242    }
243
244    /// Returns `true` if this is the *execution* of a `build.rs` script.
245    pub fn is_run_custom_build(self) -> bool {
246        self == CompileMode::RunCustomBuild
247    }
248
249    /// Returns `true` if this mode may generate an executable.
250    ///
251    /// Note that this also returns `true` for building libraries, so you also
252    /// have to check the target.
253    pub fn generates_executable(self) -> bool {
254        matches!(self, CompileMode::Test | CompileMode::Build)
255    }
256}
257
258/// Represents the high-level operation requested by the user.
259///
260/// It determines which "Cargo targets" are selected by default and influences
261/// how they will be processed. This is derived from the Cargo command the user
262/// invoked (like `cargo build` or `cargo test`).
263///
264/// Unlike [`CompileMode`], which describes the specific compilation steps for
265/// individual units, [`UserIntent`] represents the overall goal of the build
266/// process as specified by the user.
267///
268/// For example, when a user runs `cargo test`, the intent is [`UserIntent::Test`],
269/// but this might result in multiple [`CompileMode`]s for different units.
270#[derive(Clone, Copy, Debug)]
271pub enum UserIntent {
272    /// Build benchmark binaries, e.g., `cargo bench`
273    Bench,
274    /// Build binaries and libraries, e.g., `cargo run`, `cargo install`, `cargo build`.
275    Build,
276    /// Perform type-check, e.g., `cargo check`.
277    Check { test: bool },
278    /// Document packages.
279    ///
280    /// If `deps` is true, then it will also document all dependencies.
281    /// if `json` is true, the documentation output is in json format.
282    Doc { deps: bool, json: bool },
283    /// Build doctest binaries, e.g., `cargo test --doc`
284    Doctest,
285    /// Build test binaries, e.g., `cargo test`
286    Test,
287}
288
289impl UserIntent {
290    /// Returns `true` if this is generating documentation.
291    pub fn is_doc(self) -> bool {
292        matches!(self, UserIntent::Doc { .. })
293    }
294
295    /// User wants rustdoc output in JSON format.
296    pub fn wants_doc_json_output(self) -> bool {
297        matches!(self, UserIntent::Doc { json: true, .. })
298    }
299
300    /// User wants to document also for dependencies.
301    pub fn wants_deps_docs(self) -> bool {
302        matches!(self, UserIntent::Doc { deps: true, .. })
303    }
304
305    /// Returns `true` if this is any type of test (test, benchmark, doc test, or
306    /// check test).
307    pub fn is_any_test(self) -> bool {
308        matches!(
309            self,
310            UserIntent::Test
311                | UserIntent::Bench
312                | UserIntent::Check { test: true }
313                | UserIntent::Doctest
314        )
315    }
316
317    /// Returns `true` if this is something that passes `--test` to rustc.
318    pub fn is_rustc_test(self) -> bool {
319        matches!(
320            self,
321            UserIntent::Test | UserIntent::Bench | UserIntent::Check { test: true }
322        )
323    }
324}
325
326/// Kinds of build timings we can output.
327#[derive(Clone, Copy, PartialEq, Debug, Eq, Hash, PartialOrd, Ord)]
328pub enum TimingOutput {
329    /// Human-readable HTML report
330    Html,
331    /// Machine-readable JSON (unstable)
332    Json,
333}