cargo/core/compiler/
mod.rs

1//! # Interact with the compiler
2//!
3//! If you consider [`ops::cargo_compile::compile`] as a `rustc` driver but on
4//! Cargo side, this module is kinda the `rustc_interface` for that merits.
5//! It contains all the interaction between Cargo and the rustc compiler,
6//! from preparing the context for the entire build process, to scheduling
7//! and executing each unit of work (e.g. running `rustc`), to managing and
8//! caching the output artifact of a build.
9//!
10//! However, it hasn't yet exposed a clear definition of each phase or session,
11//! like what rustc has done[^1]. Also, no one knows if Cargo really needs that.
12//! To be pragmatic, here we list a handful of items you may want to learn:
13//!
14//! * [`BuildContext`] is a static context containing all information you need
15//!   before a build gets started.
16//! * [`BuildRunner`] is the center of the world, coordinating a running build and
17//!   collecting information from it.
18//! * [`custom_build`] is the home of build script executions and output parsing.
19//! * [`fingerprint`] not only defines but also executes a set of rules to
20//!   determine if a re-compile is needed.
21//! * [`job_queue`] is where the parallelism, job scheduling, and communication
22//!   machinery happen between Cargo and the compiler.
23//! * [`layout`] defines and manages output artifacts of a build in the filesystem.
24//! * [`unit_dependencies`] is for building a dependency graph for compilation
25//!   from a result of dependency resolution.
26//! * [`Unit`] contains sufficient information to build something, usually
27//!   turning into a compiler invocation in a later phase.
28//!
29//! [^1]: Maybe [`-Zbuild-plan`](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-plan)
30//!   was designed to serve that purpose but still [in flux](https://github.com/rust-lang/cargo/issues/7614).
31//!
32//! [`ops::cargo_compile::compile`]: crate::ops::compile
33
34pub mod artifact;
35mod build_config;
36pub(crate) mod build_context;
37mod build_plan;
38pub(crate) mod build_runner;
39mod compilation;
40mod compile_kind;
41mod crate_type;
42mod custom_build;
43pub(crate) mod fingerprint;
44pub mod future_incompat;
45pub(crate) mod job_queue;
46pub(crate) mod layout;
47mod links;
48mod lto;
49mod output_depinfo;
50mod output_sbom;
51pub mod rustdoc;
52pub mod standard_lib;
53mod timings;
54mod unit;
55pub mod unit_dependencies;
56pub mod unit_graph;
57
58use std::borrow::Cow;
59use std::collections::{HashMap, HashSet};
60use std::env;
61use std::ffi::{OsStr, OsString};
62use std::fmt::Display;
63use std::fs::{self, File};
64use std::io::{BufRead, BufWriter, Write};
65use std::path::{Path, PathBuf};
66use std::sync::Arc;
67
68use anyhow::{Context as _, Error};
69use lazycell::LazyCell;
70use tracing::{debug, trace};
71
72pub use self::build_config::{BuildConfig, CompileMode, MessageFormat, TimingOutput};
73pub use self::build_context::{
74    BuildContext, FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
75};
76use self::build_plan::BuildPlan;
77pub use self::build_runner::{BuildRunner, Metadata, UnitHash};
78pub use self::compilation::{Compilation, Doctest, UnitOutput};
79pub use self::compile_kind::{CompileKind, CompileKindFallback, CompileTarget};
80pub use self::crate_type::CrateType;
81pub use self::custom_build::LinkArgTarget;
82pub use self::custom_build::{BuildOutput, BuildScriptOutputs, BuildScripts};
83pub(crate) use self::fingerprint::DirtyReason;
84pub use self::job_queue::Freshness;
85use self::job_queue::{Job, JobQueue, JobState, Work};
86pub(crate) use self::layout::Layout;
87pub use self::lto::Lto;
88use self::output_depinfo::output_depinfo;
89use self::output_sbom::build_sbom;
90use self::unit_graph::UnitDep;
91use crate::core::compiler::future_incompat::FutureIncompatReport;
92pub use crate::core::compiler::unit::{Unit, UnitInterner};
93use crate::core::manifest::TargetSourcePath;
94use crate::core::profiles::{PanicStrategy, Profile, StripInner};
95use crate::core::{Feature, PackageId, Target, Verbosity};
96use crate::util::context::WarningHandling;
97use crate::util::errors::{CargoResult, VerboseError};
98use crate::util::interning::InternedString;
99use crate::util::machine_message::{self, Message};
100use crate::util::{add_path_args, internal};
101use cargo_util::{paths, ProcessBuilder, ProcessError};
102use cargo_util_schemas::manifest::TomlDebugInfo;
103use cargo_util_schemas::manifest::TomlTrimPaths;
104use cargo_util_schemas::manifest::TomlTrimPathsValue;
105use rustfix::diagnostics::Applicability;
106
107const RUSTDOC_CRATE_VERSION_FLAG: &str = "--crate-version";
108
109/// A glorified callback for executing calls to rustc. Rather than calling rustc
110/// directly, we'll use an `Executor`, giving clients an opportunity to intercept
111/// the build calls.
112pub trait Executor: Send + Sync + 'static {
113    /// Called after a rustc process invocation is prepared up-front for a given
114    /// unit of work (may still be modified for runtime-known dependencies, when
115    /// the work is actually executed).
116    fn init(&self, _build_runner: &BuildRunner<'_, '_>, _unit: &Unit) {}
117
118    /// In case of an `Err`, Cargo will not continue with the build process for
119    /// this package.
120    fn exec(
121        &self,
122        cmd: &ProcessBuilder,
123        id: PackageId,
124        target: &Target,
125        mode: CompileMode,
126        on_stdout_line: &mut dyn FnMut(&str) -> CargoResult<()>,
127        on_stderr_line: &mut dyn FnMut(&str) -> CargoResult<()>,
128    ) -> CargoResult<()>;
129
130    /// Queried when queuing each unit of work. If it returns true, then the
131    /// unit will always be rebuilt, independent of whether it needs to be.
132    fn force_rebuild(&self, _unit: &Unit) -> bool {
133        false
134    }
135}
136
137/// A `DefaultExecutor` calls rustc without doing anything else. It is Cargo's
138/// default behaviour.
139#[derive(Copy, Clone)]
140pub struct DefaultExecutor;
141
142impl Executor for DefaultExecutor {
143    fn exec(
144        &self,
145        cmd: &ProcessBuilder,
146        _id: PackageId,
147        _target: &Target,
148        _mode: CompileMode,
149        on_stdout_line: &mut dyn FnMut(&str) -> CargoResult<()>,
150        on_stderr_line: &mut dyn FnMut(&str) -> CargoResult<()>,
151    ) -> CargoResult<()> {
152        cmd.exec_with_streaming(on_stdout_line, on_stderr_line, false)
153            .map(drop)
154    }
155}
156
157/// Builds up and enqueue a list of pending jobs onto the `job` queue.
158///
159/// Starting from the `unit`, this function recursively calls itself to build
160/// all jobs for dependencies of the `unit`. Each of these jobs represents
161/// compiling a particular package.
162///
163/// Note that **no actual work is executed as part of this**, that's all done
164/// next as part of [`JobQueue::execute`] function which will run everything
165/// in order with proper parallelism.
166#[tracing::instrument(skip(build_runner, jobs, plan, exec))]
167fn compile<'gctx>(
168    build_runner: &mut BuildRunner<'_, 'gctx>,
169    jobs: &mut JobQueue<'gctx>,
170    plan: &mut BuildPlan,
171    unit: &Unit,
172    exec: &Arc<dyn Executor>,
173    force_rebuild: bool,
174) -> CargoResult<()> {
175    let bcx = build_runner.bcx;
176    let build_plan = bcx.build_config.build_plan;
177    if !build_runner.compiled.insert(unit.clone()) {
178        return Ok(());
179    }
180
181    // Build up the work to be done to compile this unit, enqueuing it once
182    // we've got everything constructed.
183    fingerprint::prepare_init(build_runner, unit)?;
184
185    let job = if unit.mode.is_run_custom_build() {
186        custom_build::prepare(build_runner, unit)?
187    } else if unit.mode.is_doc_test() {
188        // We run these targets later, so this is just a no-op for now.
189        Job::new_fresh()
190    } else if build_plan {
191        Job::new_dirty(
192            rustc(build_runner, unit, &exec.clone())?,
193            DirtyReason::FreshBuild,
194        )
195    } else {
196        let force = exec.force_rebuild(unit) || force_rebuild;
197        let mut job = fingerprint::prepare_target(build_runner, unit, force)?;
198        job.before(if job.freshness().is_dirty() {
199            let work = if unit.mode.is_doc() || unit.mode.is_doc_scrape() {
200                rustdoc(build_runner, unit)?
201            } else {
202                rustc(build_runner, unit, exec)?
203            };
204            work.then(link_targets(build_runner, unit, false)?)
205        } else {
206            // We always replay the output cache,
207            // since it might contain future-incompat-report messages
208            let show_diagnostics = unit.show_warnings(bcx.gctx)
209                && build_runner.bcx.gctx.warning_handling()? != WarningHandling::Allow;
210            let work = replay_output_cache(
211                unit.pkg.package_id(),
212                PathBuf::from(unit.pkg.manifest_path()),
213                &unit.target,
214                build_runner.files().message_cache_path(unit),
215                build_runner.bcx.build_config.message_format,
216                show_diagnostics,
217            );
218            // Need to link targets on both the dirty and fresh.
219            work.then(link_targets(build_runner, unit, true)?)
220        });
221
222        job
223    };
224    jobs.enqueue(build_runner, unit, job)?;
225
226    // Be sure to compile all dependencies of this target as well.
227    let deps = Vec::from(build_runner.unit_deps(unit)); // Create vec due to mutable borrow.
228    for dep in deps {
229        compile(build_runner, jobs, plan, &dep.unit, exec, false)?;
230    }
231    if build_plan {
232        plan.add(build_runner, unit)?;
233    }
234
235    Ok(())
236}
237
238/// Generates the warning message used when fallible doc-scrape units fail,
239/// either for rustdoc or rustc.
240fn make_failed_scrape_diagnostic(
241    build_runner: &BuildRunner<'_, '_>,
242    unit: &Unit,
243    top_line: impl Display,
244) -> String {
245    let manifest_path = unit.pkg.manifest_path();
246    let relative_manifest_path = manifest_path
247        .strip_prefix(build_runner.bcx.ws.root())
248        .unwrap_or(&manifest_path);
249
250    format!(
251        "\
252{top_line}
253    Try running with `--verbose` to see the error message.
254    If an example should not be scanned, then consider adding `doc-scrape-examples = false` to its `[[example]]` definition in {}",
255        relative_manifest_path.display()
256    )
257}
258
259/// Creates a unit of work invoking `rustc` for building the `unit`.
260fn rustc(
261    build_runner: &mut BuildRunner<'_, '_>,
262    unit: &Unit,
263    exec: &Arc<dyn Executor>,
264) -> CargoResult<Work> {
265    let mut rustc = prepare_rustc(build_runner, unit)?;
266    let build_plan = build_runner.bcx.build_config.build_plan;
267
268    let name = unit.pkg.name();
269    let buildkey = unit.buildkey();
270
271    let outputs = build_runner.outputs(unit)?;
272    let root = build_runner.files().out_dir(unit);
273
274    // Prepare the native lib state (extra `-L` and `-l` flags).
275    let build_script_outputs = Arc::clone(&build_runner.build_script_outputs);
276    let current_id = unit.pkg.package_id();
277    let manifest_path = PathBuf::from(unit.pkg.manifest_path());
278    let build_scripts = build_runner.build_scripts.get(unit).cloned();
279
280    // If we are a binary and the package also contains a library, then we
281    // don't pass the `-l` flags.
282    let pass_l_flag = unit.target.is_lib() || !unit.pkg.targets().iter().any(|t| t.is_lib());
283
284    let dep_info_name =
285        if let Some(c_extra_filename) = build_runner.files().metadata(unit).c_extra_filename() {
286            format!("{}-{}.d", unit.target.crate_name(), c_extra_filename)
287        } else {
288            format!("{}.d", unit.target.crate_name())
289        };
290    let rustc_dep_info_loc = root.join(dep_info_name);
291    let dep_info_loc = fingerprint::dep_info_loc(build_runner, unit);
292
293    let mut output_options = OutputOptions::new(build_runner, unit);
294    let package_id = unit.pkg.package_id();
295    let target = Target::clone(&unit.target);
296    let mode = unit.mode;
297
298    exec.init(build_runner, unit);
299    let exec = exec.clone();
300
301    let root_output = build_runner.files().host_dest().to_path_buf();
302    let build_dir = build_runner.bcx.ws.build_dir().into_path_unlocked();
303    let pkg_root = unit.pkg.root().to_path_buf();
304    let cwd = rustc
305        .get_cwd()
306        .unwrap_or_else(|| build_runner.bcx.gctx.cwd())
307        .to_path_buf();
308    let fingerprint_dir = build_runner.files().fingerprint_dir(unit);
309    let script_metadata = build_runner.find_build_script_metadata(unit);
310    let is_local = unit.is_local();
311    let artifact = unit.artifact;
312    let sbom_files = build_runner.sbom_output_files(unit)?;
313    let sbom = build_sbom(build_runner, unit)?;
314
315    let hide_diagnostics_for_scrape_unit = build_runner.bcx.unit_can_fail_for_docscraping(unit)
316        && !matches!(
317            build_runner.bcx.gctx.shell().verbosity(),
318            Verbosity::Verbose
319        );
320    let failed_scrape_diagnostic = hide_diagnostics_for_scrape_unit.then(|| {
321        // If this unit is needed for doc-scraping, then we generate a diagnostic that
322        // describes the set of reverse-dependencies that cause the unit to be needed.
323        let target_desc = unit.target.description_named();
324        let mut for_scrape_units = build_runner
325            .bcx
326            .scrape_units_have_dep_on(unit)
327            .into_iter()
328            .map(|unit| unit.target.description_named())
329            .collect::<Vec<_>>();
330        for_scrape_units.sort();
331        let for_scrape_units = for_scrape_units.join(", ");
332        make_failed_scrape_diagnostic(build_runner, unit, format_args!("failed to check {target_desc} in package `{name}` as a prerequisite for scraping examples from: {for_scrape_units}"))
333    });
334    if hide_diagnostics_for_scrape_unit {
335        output_options.show_diagnostics = false;
336    }
337    let env_config = Arc::clone(build_runner.bcx.gctx.env_config()?);
338    return Ok(Work::new(move |state| {
339        // Artifacts are in a different location than typical units,
340        // hence we must assure the crate- and target-dependent
341        // directory is present.
342        if artifact.is_true() {
343            paths::create_dir_all(&root)?;
344        }
345
346        // Only at runtime have we discovered what the extra -L and -l
347        // arguments are for native libraries, so we process those here. We
348        // also need to be sure to add any -L paths for our plugins to the
349        // dynamic library load path as a plugin's dynamic library may be
350        // located somewhere in there.
351        // Finally, if custom environment variables have been produced by
352        // previous build scripts, we include them in the rustc invocation.
353        if let Some(build_scripts) = build_scripts {
354            let script_outputs = build_script_outputs.lock().unwrap();
355            if !build_plan {
356                add_native_deps(
357                    &mut rustc,
358                    &script_outputs,
359                    &build_scripts,
360                    pass_l_flag,
361                    &target,
362                    current_id,
363                    mode,
364                )?;
365                add_plugin_deps(&mut rustc, &script_outputs, &build_scripts, &root_output)?;
366            }
367            add_custom_flags(&mut rustc, &script_outputs, script_metadata)?;
368        }
369
370        for output in outputs.iter() {
371            // If there is both an rmeta and rlib, rustc will prefer to use the
372            // rlib, even if it is older. Therefore, we must delete the rlib to
373            // force using the new rmeta.
374            if output.path.extension() == Some(OsStr::new("rmeta")) {
375                let dst = root.join(&output.path).with_extension("rlib");
376                if dst.exists() {
377                    paths::remove_file(&dst)?;
378                }
379            }
380
381            // Some linkers do not remove the executable, but truncate and modify it.
382            // That results in the old hard-link being modified even after renamed.
383            // We delete the old artifact here to prevent this behavior from confusing users.
384            // See rust-lang/cargo#8348.
385            if output.hardlink.is_some() && output.path.exists() {
386                _ = paths::remove_file(&output.path).map_err(|e| {
387                    tracing::debug!(
388                        "failed to delete previous output file `{:?}`: {e:?}",
389                        output.path
390                    );
391                });
392            }
393        }
394
395        state.running(&rustc);
396        let timestamp = paths::set_invocation_time(&fingerprint_dir)?;
397        if build_plan {
398            state.build_plan(buildkey, rustc.clone(), outputs.clone());
399        } else {
400            for file in sbom_files {
401                tracing::debug!("writing sbom to {}", file.display());
402                let outfile = BufWriter::new(paths::create(&file)?);
403                serde_json::to_writer(outfile, &sbom)?;
404            }
405
406            let result = exec
407                .exec(
408                    &rustc,
409                    package_id,
410                    &target,
411                    mode,
412                    &mut |line| on_stdout_line(state, line, package_id, &target),
413                    &mut |line| {
414                        on_stderr_line(
415                            state,
416                            line,
417                            package_id,
418                            &manifest_path,
419                            &target,
420                            &mut output_options,
421                        )
422                    },
423                )
424                .map_err(|e| {
425                    if output_options.errors_seen == 0 {
426                        // If we didn't expect an error, do not require --verbose to fail.
427                        // This is intended to debug
428                        // https://github.com/rust-lang/crater/issues/733, where we are seeing
429                        // Cargo exit unsuccessfully while seeming to not show any errors.
430                        e
431                    } else {
432                        verbose_if_simple_exit_code(e)
433                    }
434                })
435                .with_context(|| {
436                    // adapted from rustc_errors/src/lib.rs
437                    let warnings = match output_options.warnings_seen {
438                        0 => String::new(),
439                        1 => "; 1 warning emitted".to_string(),
440                        count => format!("; {} warnings emitted", count),
441                    };
442                    let errors = match output_options.errors_seen {
443                        0 => String::new(),
444                        1 => " due to 1 previous error".to_string(),
445                        count => format!(" due to {} previous errors", count),
446                    };
447                    let name = descriptive_pkg_name(&name, &target, &mode);
448                    format!("could not compile {name}{errors}{warnings}")
449                });
450
451            if let Err(e) = result {
452                if let Some(diagnostic) = failed_scrape_diagnostic {
453                    state.warning(diagnostic);
454                }
455
456                return Err(e);
457            }
458
459            // Exec should never return with success *and* generate an error.
460            debug_assert_eq!(output_options.errors_seen, 0);
461        }
462
463        if rustc_dep_info_loc.exists() {
464            fingerprint::translate_dep_info(
465                &rustc_dep_info_loc,
466                &dep_info_loc,
467                &cwd,
468                &pkg_root,
469                &build_dir,
470                &rustc,
471                // Do not track source files in the fingerprint for registry dependencies.
472                is_local,
473                &env_config,
474            )
475            .with_context(|| {
476                internal(format!(
477                    "could not parse/generate dep info at: {}",
478                    rustc_dep_info_loc.display()
479                ))
480            })?;
481            // This mtime shift allows Cargo to detect if a source file was
482            // modified in the middle of the build.
483            paths::set_file_time_no_err(dep_info_loc, timestamp);
484        }
485
486        Ok(())
487    }));
488
489    // Add all relevant `-L` and `-l` flags from dependencies (now calculated and
490    // present in `state`) to the command provided.
491    fn add_native_deps(
492        rustc: &mut ProcessBuilder,
493        build_script_outputs: &BuildScriptOutputs,
494        build_scripts: &BuildScripts,
495        pass_l_flag: bool,
496        target: &Target,
497        current_id: PackageId,
498        mode: CompileMode,
499    ) -> CargoResult<()> {
500        for key in build_scripts.to_link.iter() {
501            let output = build_script_outputs.get(key.1).ok_or_else(|| {
502                internal(format!(
503                    "couldn't find build script output for {}/{}",
504                    key.0, key.1
505                ))
506            })?;
507            for path in output.library_paths.iter() {
508                rustc.arg("-L").arg(path);
509            }
510
511            if key.0 == current_id {
512                if pass_l_flag {
513                    for name in output.library_links.iter() {
514                        rustc.arg("-l").arg(name);
515                    }
516                }
517            }
518
519            for (lt, arg) in &output.linker_args {
520                // There was an unintentional change where cdylibs were
521                // allowed to be passed via transitive dependencies. This
522                // clause should have been kept in the `if` block above. For
523                // now, continue allowing it for cdylib only.
524                // See https://github.com/rust-lang/cargo/issues/9562
525                if lt.applies_to(target, mode)
526                    && (key.0 == current_id || *lt == LinkArgTarget::Cdylib)
527                {
528                    rustc.arg("-C").arg(format!("link-arg={}", arg));
529                }
530            }
531        }
532        Ok(())
533    }
534}
535
536fn verbose_if_simple_exit_code(err: Error) -> Error {
537    // If a signal on unix (`code == None`) or an abnormal termination
538    // on Windows (codes like `0xC0000409`), don't hide the error details.
539    match err
540        .downcast_ref::<ProcessError>()
541        .as_ref()
542        .and_then(|perr| perr.code)
543    {
544        Some(n) if cargo_util::is_simple_exit_code(n) => VerboseError::new(err).into(),
545        _ => err,
546    }
547}
548
549/// Link the compiled target (often of form `foo-{metadata_hash}`) to the
550/// final target. This must happen during both "Fresh" and "Compile".
551fn link_targets(
552    build_runner: &mut BuildRunner<'_, '_>,
553    unit: &Unit,
554    fresh: bool,
555) -> CargoResult<Work> {
556    let bcx = build_runner.bcx;
557    let outputs = build_runner.outputs(unit)?;
558    let export_dir = build_runner.files().export_dir();
559    let package_id = unit.pkg.package_id();
560    let manifest_path = PathBuf::from(unit.pkg.manifest_path());
561    let profile = unit.profile.clone();
562    let unit_mode = unit.mode;
563    let features = unit.features.iter().map(|s| s.to_string()).collect();
564    let json_messages = bcx.build_config.emit_json();
565    let executable = build_runner.get_executable(unit)?;
566    let mut target = Target::clone(&unit.target);
567    if let TargetSourcePath::Metabuild = target.src_path() {
568        // Give it something to serialize.
569        let path = unit
570            .pkg
571            .manifest()
572            .metabuild_path(build_runner.bcx.ws.build_dir());
573        target.set_src_path(TargetSourcePath::Path(path));
574    }
575
576    Ok(Work::new(move |state| {
577        // If we're a "root crate", e.g., the target of this compilation, then we
578        // hard link our outputs out of the `deps` directory into the directory
579        // above. This means that `cargo build` will produce binaries in
580        // `target/debug` which one probably expects.
581        let mut destinations = vec![];
582        for output in outputs.iter() {
583            let src = &output.path;
584            // This may have been a `cargo rustc` command which changes the
585            // output, so the source may not actually exist.
586            if !src.exists() {
587                continue;
588            }
589            let Some(dst) = output.hardlink.as_ref() else {
590                destinations.push(src.clone());
591                continue;
592            };
593            destinations.push(dst.clone());
594            paths::link_or_copy(src, dst)?;
595            if let Some(ref path) = output.export_path {
596                let export_dir = export_dir.as_ref().unwrap();
597                paths::create_dir_all(export_dir)?;
598
599                paths::link_or_copy(src, path)?;
600            }
601        }
602
603        if json_messages {
604            let debuginfo = match profile.debuginfo.into_inner() {
605                TomlDebugInfo::None => machine_message::ArtifactDebuginfo::Int(0),
606                TomlDebugInfo::Limited => machine_message::ArtifactDebuginfo::Int(1),
607                TomlDebugInfo::Full => machine_message::ArtifactDebuginfo::Int(2),
608                TomlDebugInfo::LineDirectivesOnly => {
609                    machine_message::ArtifactDebuginfo::Named("line-directives-only")
610                }
611                TomlDebugInfo::LineTablesOnly => {
612                    machine_message::ArtifactDebuginfo::Named("line-tables-only")
613                }
614            };
615            let art_profile = machine_message::ArtifactProfile {
616                opt_level: profile.opt_level.as_str(),
617                debuginfo: Some(debuginfo),
618                debug_assertions: profile.debug_assertions,
619                overflow_checks: profile.overflow_checks,
620                test: unit_mode.is_any_test(),
621            };
622
623            let msg = machine_message::Artifact {
624                package_id: package_id.to_spec(),
625                manifest_path,
626                target: &target,
627                profile: art_profile,
628                features,
629                filenames: destinations,
630                executable,
631                fresh,
632            }
633            .to_json_string();
634            state.stdout(msg)?;
635        }
636        Ok(())
637    }))
638}
639
640// For all plugin dependencies, add their -L paths (now calculated and present
641// in `build_script_outputs`) to the dynamic library load path for the command
642// to execute.
643fn add_plugin_deps(
644    rustc: &mut ProcessBuilder,
645    build_script_outputs: &BuildScriptOutputs,
646    build_scripts: &BuildScripts,
647    root_output: &Path,
648) -> CargoResult<()> {
649    let var = paths::dylib_path_envvar();
650    let search_path = rustc.get_env(var).unwrap_or_default();
651    let mut search_path = env::split_paths(&search_path).collect::<Vec<_>>();
652    for (pkg_id, metadata) in &build_scripts.plugins {
653        let output = build_script_outputs
654            .get(*metadata)
655            .ok_or_else(|| internal(format!("couldn't find libs for plugin dep {}", pkg_id)))?;
656        search_path.append(&mut filter_dynamic_search_path(
657            output.library_paths.iter(),
658            root_output,
659        ));
660    }
661    let search_path = paths::join_paths(&search_path, var)?;
662    rustc.env(var, &search_path);
663    Ok(())
664}
665
666// Determine paths to add to the dynamic search path from -L entries
667//
668// Strip off prefixes like "native=" or "framework=" and filter out directories
669// **not** inside our output directory since they are likely spurious and can cause
670// clashes with system shared libraries (issue #3366).
671fn filter_dynamic_search_path<'a, I>(paths: I, root_output: &Path) -> Vec<PathBuf>
672where
673    I: Iterator<Item = &'a PathBuf>,
674{
675    let mut search_path = vec![];
676    for dir in paths {
677        let dir = match dir.to_str().and_then(|s| s.split_once("=")) {
678            Some(("native" | "crate" | "dependency" | "framework" | "all", path)) => path.into(),
679            _ => dir.clone(),
680        };
681        if dir.starts_with(&root_output) {
682            search_path.push(dir);
683        } else {
684            debug!(
685                "Not including path {} in runtime library search path because it is \
686                 outside target root {}",
687                dir.display(),
688                root_output.display()
689            );
690        }
691    }
692    search_path
693}
694
695/// Prepares flags and environments we can compute for a `rustc` invocation
696/// before the job queue starts compiling any unit.
697///
698/// This builds a static view of the invocation. Flags depending on the
699/// completion of other units will be added later in runtime, such as flags
700/// from build scripts.
701fn prepare_rustc(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<ProcessBuilder> {
702    let gctx = build_runner.bcx.gctx;
703    let is_primary = build_runner.is_primary_package(unit);
704    let is_workspace = build_runner.bcx.ws.is_member(&unit.pkg);
705
706    let mut base = build_runner
707        .compilation
708        .rustc_process(unit, is_primary, is_workspace)?;
709    build_base_args(build_runner, &mut base, unit)?;
710
711    base.inherit_jobserver(&build_runner.jobserver);
712    build_deps_args(&mut base, build_runner, unit)?;
713    add_cap_lints(build_runner.bcx, unit, &mut base);
714    if let Some(args) = build_runner.bcx.extra_args_for(unit) {
715        base.args(args);
716    }
717    base.args(&unit.rustflags);
718    if gctx.cli_unstable().binary_dep_depinfo {
719        base.arg("-Z").arg("binary-dep-depinfo");
720    }
721    if build_runner.bcx.gctx.cli_unstable().checksum_freshness {
722        base.arg("-Z").arg("checksum-hash-algorithm=blake3");
723    }
724
725    if is_primary {
726        base.env("CARGO_PRIMARY_PACKAGE", "1");
727        let file_list = std::env::join_paths(build_runner.sbom_output_files(unit)?)?;
728        base.env("CARGO_SBOM_PATH", file_list);
729    }
730
731    if unit.target.is_test() || unit.target.is_bench() {
732        let tmp = build_runner.files().layout(unit.kind).prepare_tmp()?;
733        base.env("CARGO_TARGET_TMPDIR", tmp.display().to_string());
734    }
735
736    Ok(base)
737}
738
739/// Prepares flags and environments we can compute for a `rustdoc` invocation
740/// before the job queue starts compiling any unit.
741///
742/// This builds a static view of the invocation. Flags depending on the
743/// completion of other units will be added later in runtime, such as flags
744/// from build scripts.
745fn prepare_rustdoc(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<ProcessBuilder> {
746    let bcx = build_runner.bcx;
747    // script_metadata is not needed here, it is only for tests.
748    let mut rustdoc = build_runner.compilation.rustdoc_process(unit, None)?;
749    rustdoc.inherit_jobserver(&build_runner.jobserver);
750    let crate_name = unit.target.crate_name();
751    rustdoc.arg("--crate-name").arg(&crate_name);
752    add_path_args(bcx.ws, unit, &mut rustdoc);
753    add_cap_lints(bcx, unit, &mut rustdoc);
754
755    if let CompileKind::Target(target) = unit.kind {
756        rustdoc.arg("--target").arg(target.rustc_target());
757    }
758    let doc_dir = build_runner.files().out_dir(unit);
759    rustdoc.arg("-o").arg(&doc_dir);
760    rustdoc.args(&features_args(unit));
761    rustdoc.args(&check_cfg_args(unit));
762
763    add_error_format_and_color(build_runner, &mut rustdoc);
764    add_allow_features(build_runner, &mut rustdoc);
765
766    if let Some(trim_paths) = unit.profile.trim_paths.as_ref() {
767        trim_paths_args_rustdoc(&mut rustdoc, build_runner, unit, trim_paths)?;
768    }
769
770    rustdoc.args(unit.pkg.manifest().lint_rustflags());
771
772    let metadata = build_runner.metadata_for_doc_units[unit];
773    rustdoc
774        .arg("-C")
775        .arg(format!("metadata={}", metadata.c_metadata()));
776
777    if unit.mode.is_doc_scrape() {
778        debug_assert!(build_runner.bcx.scrape_units.contains(unit));
779
780        if unit.target.is_test() {
781            rustdoc.arg("--scrape-tests");
782        }
783
784        rustdoc.arg("-Zunstable-options");
785
786        rustdoc
787            .arg("--scrape-examples-output-path")
788            .arg(scrape_output_path(build_runner, unit)?);
789
790        // Only scrape example for items from crates in the workspace, to reduce generated file size
791        for pkg in build_runner.bcx.packages.packages() {
792            let names = pkg
793                .targets()
794                .iter()
795                .map(|target| target.crate_name())
796                .collect::<HashSet<_>>();
797            for name in names {
798                rustdoc.arg("--scrape-examples-target-crate").arg(name);
799            }
800        }
801    }
802
803    if should_include_scrape_units(build_runner.bcx, unit) {
804        rustdoc.arg("-Zunstable-options");
805    }
806
807    build_deps_args(&mut rustdoc, build_runner, unit)?;
808    rustdoc::add_root_urls(build_runner, unit, &mut rustdoc)?;
809
810    rustdoc::add_output_format(build_runner, unit, &mut rustdoc)?;
811
812    if let Some(args) = build_runner.bcx.extra_args_for(unit) {
813        rustdoc.args(args);
814    }
815    rustdoc.args(&unit.rustdocflags);
816
817    if !crate_version_flag_already_present(&rustdoc) {
818        append_crate_version_flag(unit, &mut rustdoc);
819    }
820
821    Ok(rustdoc)
822}
823
824/// Creates a unit of work invoking `rustdoc` for documenting the `unit`.
825fn rustdoc(build_runner: &mut BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<Work> {
826    let mut rustdoc = prepare_rustdoc(build_runner, unit)?;
827
828    let crate_name = unit.target.crate_name();
829    let doc_dir = build_runner.files().out_dir(unit);
830    // Create the documentation directory ahead of time as rustdoc currently has
831    // a bug where concurrent invocations will race to create this directory if
832    // it doesn't already exist.
833    paths::create_dir_all(&doc_dir)?;
834
835    let target_desc = unit.target.description_named();
836    let name = unit.pkg.name();
837    let build_script_outputs = Arc::clone(&build_runner.build_script_outputs);
838    let package_id = unit.pkg.package_id();
839    let manifest_path = PathBuf::from(unit.pkg.manifest_path());
840    let target = Target::clone(&unit.target);
841    let mut output_options = OutputOptions::new(build_runner, unit);
842    let script_metadata = build_runner.find_build_script_metadata(unit);
843    let scrape_outputs = if should_include_scrape_units(build_runner.bcx, unit) {
844        Some(
845            build_runner
846                .bcx
847                .scrape_units
848                .iter()
849                .map(|unit| {
850                    Ok((
851                        build_runner.files().metadata(unit).unit_id(),
852                        scrape_output_path(build_runner, unit)?,
853                    ))
854                })
855                .collect::<CargoResult<HashMap<_, _>>>()?,
856        )
857    } else {
858        None
859    };
860
861    let failed_scrape_units = Arc::clone(&build_runner.failed_scrape_units);
862    let hide_diagnostics_for_scrape_unit = build_runner.bcx.unit_can_fail_for_docscraping(unit)
863        && !matches!(
864            build_runner.bcx.gctx.shell().verbosity(),
865            Verbosity::Verbose
866        );
867    let failed_scrape_diagnostic = hide_diagnostics_for_scrape_unit.then(|| {
868        make_failed_scrape_diagnostic(
869            build_runner,
870            unit,
871            format_args!("failed to scan {target_desc} in package `{name}` for example code usage"),
872        )
873    });
874    if hide_diagnostics_for_scrape_unit {
875        output_options.show_diagnostics = false;
876    }
877
878    Ok(Work::new(move |state| {
879        add_custom_flags(
880            &mut rustdoc,
881            &build_script_outputs.lock().unwrap(),
882            script_metadata,
883        )?;
884
885        // Add the output of scraped examples to the rustdoc command.
886        // This action must happen after the unit's dependencies have finished,
887        // because some of those deps may be Docscrape units which have failed.
888        // So we dynamically determine which `--with-examples` flags to pass here.
889        if let Some(scrape_outputs) = scrape_outputs {
890            let failed_scrape_units = failed_scrape_units.lock().unwrap();
891            for (metadata, output_path) in &scrape_outputs {
892                if !failed_scrape_units.contains(metadata) {
893                    rustdoc.arg("--with-examples").arg(output_path);
894                }
895            }
896        }
897
898        let crate_dir = doc_dir.join(&crate_name);
899        if crate_dir.exists() {
900            // Remove output from a previous build. This ensures that stale
901            // files for removed items are removed.
902            debug!("removing pre-existing doc directory {:?}", crate_dir);
903            paths::remove_dir_all(crate_dir)?;
904        }
905        state.running(&rustdoc);
906
907        let result = rustdoc
908            .exec_with_streaming(
909                &mut |line| on_stdout_line(state, line, package_id, &target),
910                &mut |line| {
911                    on_stderr_line(
912                        state,
913                        line,
914                        package_id,
915                        &manifest_path,
916                        &target,
917                        &mut output_options,
918                    )
919                },
920                false,
921            )
922            .map_err(verbose_if_simple_exit_code)
923            .with_context(|| format!("could not document `{}`", name));
924
925        if let Err(e) = result {
926            if let Some(diagnostic) = failed_scrape_diagnostic {
927                state.warning(diagnostic);
928            }
929
930            return Err(e);
931        }
932
933        Ok(())
934    }))
935}
936
937// The --crate-version flag could have already been passed in RUSTDOCFLAGS
938// or as an extra compiler argument for rustdoc
939fn crate_version_flag_already_present(rustdoc: &ProcessBuilder) -> bool {
940    rustdoc.get_args().any(|flag| {
941        flag.to_str()
942            .map_or(false, |flag| flag.starts_with(RUSTDOC_CRATE_VERSION_FLAG))
943    })
944}
945
946fn append_crate_version_flag(unit: &Unit, rustdoc: &mut ProcessBuilder) {
947    rustdoc
948        .arg(RUSTDOC_CRATE_VERSION_FLAG)
949        .arg(unit.pkg.version().to_string());
950}
951
952/// Adds [`--cap-lints`] to the command to execute.
953///
954/// [`--cap-lints`]: https://doc.rust-lang.org/nightly/rustc/lints/levels.html#capping-lints
955fn add_cap_lints(bcx: &BuildContext<'_, '_>, unit: &Unit, cmd: &mut ProcessBuilder) {
956    // If this is an upstream dep we don't want warnings from, turn off all
957    // lints.
958    if !unit.show_warnings(bcx.gctx) {
959        cmd.arg("--cap-lints").arg("allow");
960
961    // If this is an upstream dep but we *do* want warnings, make sure that they
962    // don't fail compilation.
963    } else if !unit.is_local() {
964        cmd.arg("--cap-lints").arg("warn");
965    }
966}
967
968/// Forwards [`-Zallow-features`] if it is set for cargo.
969///
970/// [`-Zallow-features`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#allow-features
971fn add_allow_features(build_runner: &BuildRunner<'_, '_>, cmd: &mut ProcessBuilder) {
972    if let Some(allow) = &build_runner.bcx.gctx.cli_unstable().allow_features {
973        use std::fmt::Write;
974        let mut arg = String::from("-Zallow-features=");
975        for f in allow {
976            let _ = write!(&mut arg, "{f},");
977        }
978        cmd.arg(arg.trim_end_matches(','));
979    }
980}
981
982/// Adds [`--error-format`] to the command to execute.
983///
984/// Cargo always uses JSON output. This has several benefits, such as being
985/// easier to parse, handles changing formats (for replaying cached messages),
986/// ensures atomic output (so messages aren't interleaved), allows for
987/// intercepting messages like rmeta artifacts, etc. rustc includes a
988/// "rendered" field in the JSON message with the message properly formatted,
989/// which Cargo will extract and display to the user.
990///
991/// [`--error-format`]: https://doc.rust-lang.org/nightly/rustc/command-line-arguments.html#--error-format-control-how-errors-are-produced
992fn add_error_format_and_color(build_runner: &BuildRunner<'_, '_>, cmd: &mut ProcessBuilder) {
993    cmd.arg("--error-format=json");
994    let mut json = String::from("--json=diagnostic-rendered-ansi,artifacts,future-incompat");
995
996    match build_runner.bcx.build_config.message_format {
997        MessageFormat::Short | MessageFormat::Json { short: true, .. } => {
998            json.push_str(",diagnostic-short");
999        }
1000        _ => {}
1001    }
1002    cmd.arg(json);
1003
1004    let gctx = build_runner.bcx.gctx;
1005    if let Some(width) = gctx.shell().err_width().diagnostic_terminal_width() {
1006        cmd.arg(format!("--diagnostic-width={width}"));
1007    }
1008}
1009
1010/// Adds essential rustc flags and environment variables to the command to execute.
1011fn build_base_args(
1012    build_runner: &BuildRunner<'_, '_>,
1013    cmd: &mut ProcessBuilder,
1014    unit: &Unit,
1015) -> CargoResult<()> {
1016    assert!(!unit.mode.is_run_custom_build());
1017
1018    let bcx = build_runner.bcx;
1019    let Profile {
1020        ref opt_level,
1021        codegen_backend,
1022        codegen_units,
1023        debuginfo,
1024        debug_assertions,
1025        split_debuginfo,
1026        overflow_checks,
1027        rpath,
1028        ref panic,
1029        incremental,
1030        strip,
1031        rustflags: profile_rustflags,
1032        trim_paths,
1033        ..
1034    } = unit.profile.clone();
1035    let test = unit.mode.is_any_test();
1036
1037    cmd.arg("--crate-name").arg(&unit.target.crate_name());
1038
1039    let edition = unit.target.edition();
1040    edition.cmd_edition_arg(cmd);
1041
1042    add_path_args(bcx.ws, unit, cmd);
1043    add_error_format_and_color(build_runner, cmd);
1044    add_allow_features(build_runner, cmd);
1045
1046    let mut contains_dy_lib = false;
1047    if !test {
1048        for crate_type in &unit.target.rustc_crate_types() {
1049            cmd.arg("--crate-type").arg(crate_type.as_str());
1050            contains_dy_lib |= crate_type == &CrateType::Dylib;
1051        }
1052    }
1053
1054    if unit.mode.is_check() {
1055        cmd.arg("--emit=dep-info,metadata");
1056    } else if !unit.requires_upstream_objects() {
1057        // Always produce metadata files for rlib outputs. Metadata may be used
1058        // in this session for a pipelined compilation, or it may be used in a
1059        // future Cargo session as part of a pipelined compile.
1060        cmd.arg("--emit=dep-info,metadata,link");
1061    } else {
1062        cmd.arg("--emit=dep-info,link");
1063    }
1064
1065    let prefer_dynamic = (unit.target.for_host() && !unit.target.is_custom_build())
1066        || (contains_dy_lib && !build_runner.is_primary_package(unit));
1067    if prefer_dynamic {
1068        cmd.arg("-C").arg("prefer-dynamic");
1069    }
1070
1071    if opt_level.as_str() != "0" {
1072        cmd.arg("-C").arg(&format!("opt-level={}", opt_level));
1073    }
1074
1075    if *panic != PanicStrategy::Unwind {
1076        cmd.arg("-C").arg(format!("panic={}", panic));
1077    }
1078
1079    cmd.args(&lto_args(build_runner, unit));
1080
1081    if let Some(backend) = codegen_backend {
1082        cmd.arg("-Z").arg(&format!("codegen-backend={}", backend));
1083    }
1084
1085    if let Some(n) = codegen_units {
1086        cmd.arg("-C").arg(&format!("codegen-units={}", n));
1087    }
1088
1089    let debuginfo = debuginfo.into_inner();
1090    // Shorten the number of arguments if possible.
1091    if debuginfo != TomlDebugInfo::None {
1092        cmd.arg("-C").arg(format!("debuginfo={debuginfo}"));
1093        // This is generally just an optimization on build time so if we don't
1094        // pass it then it's ok. The values for the flag (off, packed, unpacked)
1095        // may be supported or not depending on the platform, so availability is
1096        // checked per-value. For example, at the time of writing this code, on
1097        // Windows the only stable valid value for split-debuginfo is "packed",
1098        // while on Linux "unpacked" is also stable.
1099        if let Some(split) = split_debuginfo {
1100            if build_runner
1101                .bcx
1102                .target_data
1103                .info(unit.kind)
1104                .supports_debuginfo_split(split)
1105            {
1106                cmd.arg("-C").arg(format!("split-debuginfo={split}"));
1107            }
1108        }
1109    }
1110
1111    if let Some(trim_paths) = trim_paths {
1112        trim_paths_args(cmd, build_runner, unit, &trim_paths)?;
1113    }
1114
1115    cmd.args(unit.pkg.manifest().lint_rustflags());
1116    cmd.args(&profile_rustflags);
1117
1118    // `-C overflow-checks` is implied by the setting of `-C debug-assertions`,
1119    // so we only need to provide `-C overflow-checks` if it differs from
1120    // the value of `-C debug-assertions` we would provide.
1121    if opt_level.as_str() != "0" {
1122        if debug_assertions {
1123            cmd.args(&["-C", "debug-assertions=on"]);
1124            if !overflow_checks {
1125                cmd.args(&["-C", "overflow-checks=off"]);
1126            }
1127        } else if overflow_checks {
1128            cmd.args(&["-C", "overflow-checks=on"]);
1129        }
1130    } else if !debug_assertions {
1131        cmd.args(&["-C", "debug-assertions=off"]);
1132        if overflow_checks {
1133            cmd.args(&["-C", "overflow-checks=on"]);
1134        }
1135    } else if !overflow_checks {
1136        cmd.args(&["-C", "overflow-checks=off"]);
1137    }
1138
1139    if test && unit.target.harness() {
1140        cmd.arg("--test");
1141
1142        // Cargo has historically never compiled `--test` binaries with
1143        // `panic=abort` because the `test` crate itself didn't support it.
1144        // Support is now upstream, however, but requires an unstable flag to be
1145        // passed when compiling the test. We require, in Cargo, an unstable
1146        // flag to pass to rustc, so register that here. Eventually this flag
1147        // will simply not be needed when the behavior is stabilized in the Rust
1148        // compiler itself.
1149        if *panic == PanicStrategy::Abort {
1150            cmd.arg("-Z").arg("panic-abort-tests");
1151        }
1152    } else if test {
1153        cmd.arg("--cfg").arg("test");
1154    }
1155
1156    cmd.args(&features_args(unit));
1157    cmd.args(&check_cfg_args(unit));
1158
1159    let meta = build_runner.files().metadata(unit);
1160    cmd.arg("-C")
1161        .arg(&format!("metadata={}", meta.c_metadata()));
1162    if let Some(c_extra_filename) = meta.c_extra_filename() {
1163        cmd.arg("-C")
1164            .arg(&format!("extra-filename=-{c_extra_filename}"));
1165    }
1166
1167    if rpath {
1168        cmd.arg("-C").arg("rpath");
1169    }
1170
1171    cmd.arg("--out-dir")
1172        .arg(&build_runner.files().out_dir(unit));
1173
1174    fn opt(cmd: &mut ProcessBuilder, key: &str, prefix: &str, val: Option<&OsStr>) {
1175        if let Some(val) = val {
1176            let mut joined = OsString::from(prefix);
1177            joined.push(val);
1178            cmd.arg(key).arg(joined);
1179        }
1180    }
1181
1182    if let CompileKind::Target(n) = unit.kind {
1183        cmd.arg("--target").arg(n.rustc_target());
1184    }
1185
1186    opt(
1187        cmd,
1188        "-C",
1189        "linker=",
1190        build_runner
1191            .compilation
1192            .target_linker(unit.kind)
1193            .as_ref()
1194            .map(|s| s.as_ref()),
1195    );
1196    if incremental {
1197        let dir = build_runner
1198            .files()
1199            .layout(unit.kind)
1200            .incremental()
1201            .as_os_str();
1202        opt(cmd, "-C", "incremental=", Some(dir));
1203    }
1204
1205    let strip = strip.into_inner();
1206    if strip != StripInner::None {
1207        cmd.arg("-C").arg(format!("strip={}", strip));
1208    }
1209
1210    if unit.is_std {
1211        // -Zforce-unstable-if-unmarked prevents the accidental use of
1212        // unstable crates within the sysroot (such as "extern crate libc" or
1213        // any non-public crate in the sysroot).
1214        //
1215        // RUSTC_BOOTSTRAP allows unstable features on stable.
1216        cmd.arg("-Z")
1217            .arg("force-unstable-if-unmarked")
1218            .env("RUSTC_BOOTSTRAP", "1");
1219    }
1220
1221    // Add `CARGO_BIN_EXE_` environment variables for building tests.
1222    if unit.target.is_test() || unit.target.is_bench() {
1223        for bin_target in unit
1224            .pkg
1225            .manifest()
1226            .targets()
1227            .iter()
1228            .filter(|target| target.is_bin())
1229        {
1230            let exe_path = build_runner.files().bin_link_for_target(
1231                bin_target,
1232                unit.kind,
1233                build_runner.bcx,
1234            )?;
1235            let name = bin_target
1236                .binary_filename()
1237                .unwrap_or(bin_target.name().to_string());
1238            let key = format!("CARGO_BIN_EXE_{}", name);
1239            cmd.env(&key, exe_path);
1240        }
1241    }
1242    Ok(())
1243}
1244
1245/// All active features for the unit passed as `--cfg features=<feature-name>`.
1246fn features_args(unit: &Unit) -> Vec<OsString> {
1247    let mut args = Vec::with_capacity(unit.features.len() * 2);
1248
1249    for feat in &unit.features {
1250        args.push(OsString::from("--cfg"));
1251        args.push(OsString::from(format!("feature=\"{}\"", feat)));
1252    }
1253
1254    args
1255}
1256
1257/// Like [`trim_paths_args`] but for rustdoc invocations.
1258fn trim_paths_args_rustdoc(
1259    cmd: &mut ProcessBuilder,
1260    build_runner: &BuildRunner<'_, '_>,
1261    unit: &Unit,
1262    trim_paths: &TomlTrimPaths,
1263) -> CargoResult<()> {
1264    match trim_paths {
1265        // rustdoc supports diagnostics trimming only.
1266        TomlTrimPaths::Values(values) if !values.contains(&TomlTrimPathsValue::Diagnostics) => {
1267            return Ok(())
1268        }
1269        _ => {}
1270    }
1271
1272    // feature gate was checked during manifest/config parsing.
1273    cmd.arg("-Zunstable-options");
1274
1275    // Order of `--remap-path-prefix` flags is important for `-Zbuild-std`.
1276    // We want to show `/rustc/<hash>/library/std` instead of `std-0.0.0`.
1277    cmd.arg(package_remap(build_runner, unit));
1278    cmd.arg(sysroot_remap(build_runner, unit));
1279
1280    Ok(())
1281}
1282
1283/// Generates the `--remap-path-scope` and `--remap-path-prefix` for [RFC 3127].
1284/// See also unstable feature [`-Ztrim-paths`].
1285///
1286/// [RFC 3127]: https://rust-lang.github.io/rfcs/3127-trim-paths.html
1287/// [`-Ztrim-paths`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#profile-trim-paths-option
1288fn trim_paths_args(
1289    cmd: &mut ProcessBuilder,
1290    build_runner: &BuildRunner<'_, '_>,
1291    unit: &Unit,
1292    trim_paths: &TomlTrimPaths,
1293) -> CargoResult<()> {
1294    if trim_paths.is_none() {
1295        return Ok(());
1296    }
1297
1298    // feature gate was checked during manifest/config parsing.
1299    cmd.arg("-Zunstable-options");
1300    cmd.arg(format!("-Zremap-path-scope={trim_paths}"));
1301
1302    // Order of `--remap-path-prefix` flags is important for `-Zbuild-std`.
1303    // We want to show `/rustc/<hash>/library/std` instead of `std-0.0.0`.
1304    cmd.arg(package_remap(build_runner, unit));
1305    cmd.arg(sysroot_remap(build_runner, unit));
1306
1307    Ok(())
1308}
1309
1310/// Path prefix remap rules for sysroot.
1311///
1312/// This remap logic aligns with rustc:
1313/// <https://github.com/rust-lang/rust/blob/c2ef3516/src/bootstrap/src/lib.rs#L1113-L1116>
1314fn sysroot_remap(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> OsString {
1315    let mut remap = OsString::from("--remap-path-prefix=");
1316    remap.push({
1317        // See also `detect_sysroot_src_path()`.
1318        let mut sysroot = build_runner.bcx.target_data.info(unit.kind).sysroot.clone();
1319        sysroot.push("lib");
1320        sysroot.push("rustlib");
1321        sysroot.push("src");
1322        sysroot.push("rust");
1323        sysroot
1324    });
1325    remap.push("=");
1326    remap.push("/rustc/");
1327    if let Some(commit_hash) = build_runner.bcx.rustc().commit_hash.as_ref() {
1328        remap.push(commit_hash);
1329    } else {
1330        remap.push(build_runner.bcx.rustc().version.to_string());
1331    }
1332    remap
1333}
1334
1335/// Path prefix remap rules for dependencies.
1336///
1337/// * Git dependencies: remove `~/.cargo/git/checkouts` prefix.
1338/// * Registry dependencies: remove `~/.cargo/registry/src` prefix.
1339/// * Others (e.g. path dependencies):
1340///     * relative paths to workspace root if inside the workspace directory.
1341///     * otherwise remapped to `<pkg>-<version>`.
1342fn package_remap(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> OsString {
1343    let pkg_root = unit.pkg.root();
1344    let ws_root = build_runner.bcx.ws.root();
1345    let mut remap = OsString::from("--remap-path-prefix=");
1346    let source_id = unit.pkg.package_id().source_id();
1347    if source_id.is_git() {
1348        remap.push(
1349            build_runner
1350                .bcx
1351                .gctx
1352                .git_checkouts_path()
1353                .as_path_unlocked(),
1354        );
1355        remap.push("=");
1356    } else if source_id.is_registry() {
1357        remap.push(
1358            build_runner
1359                .bcx
1360                .gctx
1361                .registry_source_path()
1362                .as_path_unlocked(),
1363        );
1364        remap.push("=");
1365    } else if pkg_root.strip_prefix(ws_root).is_ok() {
1366        remap.push(ws_root);
1367        remap.push("=."); // remap to relative rustc work dir explicitly
1368    } else {
1369        remap.push(pkg_root);
1370        remap.push("=");
1371        remap.push(unit.pkg.name());
1372        remap.push("-");
1373        remap.push(unit.pkg.version().to_string());
1374    }
1375    remap
1376}
1377
1378/// Generates the `--check-cfg` arguments for the `unit`.
1379fn check_cfg_args(unit: &Unit) -> Vec<OsString> {
1380    // The routine below generates the --check-cfg arguments. Our goals here are to
1381    // enable the checking of conditionals and pass the list of declared features.
1382    //
1383    // In the simplified case, it would resemble something like this:
1384    //
1385    //   --check-cfg=cfg() --check-cfg=cfg(feature, values(...))
1386    //
1387    // but having `cfg()` is redundant with the second argument (as well-known names
1388    // and values are implicitly enabled when one or more `--check-cfg` argument is
1389    // passed) so we don't emit it and just pass:
1390    //
1391    //   --check-cfg=cfg(feature, values(...))
1392    //
1393    // This way, even if there are no declared features, the config `feature` will
1394    // still be expected, meaning users would get "unexpected value" instead of name.
1395    // This wasn't always the case, see rust-lang#119930 for some details.
1396
1397    let gross_cap_estimation = unit.pkg.summary().features().len() * 7 + 25;
1398    let mut arg_feature = OsString::with_capacity(gross_cap_estimation);
1399
1400    arg_feature.push("cfg(feature, values(");
1401    for (i, feature) in unit.pkg.summary().features().keys().enumerate() {
1402        if i != 0 {
1403            arg_feature.push(", ");
1404        }
1405        arg_feature.push("\"");
1406        arg_feature.push(feature);
1407        arg_feature.push("\"");
1408    }
1409    arg_feature.push("))");
1410
1411    // In addition to the package features, we also include the `test` cfg (since
1412    // compiler-team#785, as to be able to someday apply yt conditionaly), as well
1413    // the `docsrs` cfg from the docs.rs service.
1414    //
1415    // We include `docsrs` here (in Cargo) instead of rustc, since there is a much closer
1416    // relationship between Cargo and docs.rs than rustc and docs.rs. In particular, all
1417    // users of docs.rs use Cargo, but not all users of rustc (like Rust-for-Linux) use docs.rs.
1418
1419    vec![
1420        OsString::from("--check-cfg"),
1421        OsString::from("cfg(docsrs,test)"),
1422        OsString::from("--check-cfg"),
1423        arg_feature,
1424    ]
1425}
1426
1427/// Adds LTO related codegen flags.
1428fn lto_args(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> Vec<OsString> {
1429    let mut result = Vec::new();
1430    let mut push = |arg: &str| {
1431        result.push(OsString::from("-C"));
1432        result.push(OsString::from(arg));
1433    };
1434    match build_runner.lto[unit] {
1435        lto::Lto::Run(None) => push("lto"),
1436        lto::Lto::Run(Some(s)) => push(&format!("lto={}", s)),
1437        lto::Lto::Off => {
1438            push("lto=off");
1439            push("embed-bitcode=no");
1440        }
1441        lto::Lto::ObjectAndBitcode => {} // this is rustc's default
1442        lto::Lto::OnlyBitcode => push("linker-plugin-lto"),
1443        lto::Lto::OnlyObject => push("embed-bitcode=no"),
1444    }
1445    result
1446}
1447
1448/// Adds dependency-relevant rustc flags and environment variables
1449/// to the command to execute, such as [`-L`] and [`--extern`].
1450///
1451/// [`-L`]: https://doc.rust-lang.org/nightly/rustc/command-line-arguments.html#-l-add-a-directory-to-the-library-search-path
1452/// [`--extern`]: https://doc.rust-lang.org/nightly/rustc/command-line-arguments.html#--extern-specify-where-an-external-library-is-located
1453fn build_deps_args(
1454    cmd: &mut ProcessBuilder,
1455    build_runner: &BuildRunner<'_, '_>,
1456    unit: &Unit,
1457) -> CargoResult<()> {
1458    let bcx = build_runner.bcx;
1459    cmd.arg("-L").arg(&{
1460        let mut deps = OsString::from("dependency=");
1461        deps.push(build_runner.files().deps_dir(unit));
1462        deps
1463    });
1464
1465    // Be sure that the host path is also listed. This'll ensure that proc macro
1466    // dependencies are correctly found (for reexported macros).
1467    if !unit.kind.is_host() {
1468        cmd.arg("-L").arg(&{
1469            let mut deps = OsString::from("dependency=");
1470            deps.push(build_runner.files().host_deps());
1471            deps
1472        });
1473    }
1474
1475    let deps = build_runner.unit_deps(unit);
1476
1477    // If there is not one linkable target but should, rustc fails later
1478    // on if there is an `extern crate` for it. This may turn into a hard
1479    // error in the future (see PR #4797).
1480    if !deps
1481        .iter()
1482        .any(|dep| !dep.unit.mode.is_doc() && dep.unit.target.is_linkable())
1483    {
1484        if let Some(dep) = deps.iter().find(|dep| {
1485            !dep.unit.mode.is_doc() && dep.unit.target.is_lib() && !dep.unit.artifact.is_true()
1486        }) {
1487            bcx.gctx.shell().warn(format!(
1488                "The package `{}` \
1489                 provides no linkable target. The compiler might raise an error while compiling \
1490                 `{}`. Consider adding 'dylib' or 'rlib' to key `crate-type` in `{}`'s \
1491                 Cargo.toml. This warning might turn into a hard error in the future.",
1492                dep.unit.target.crate_name(),
1493                unit.target.crate_name(),
1494                dep.unit.target.crate_name()
1495            ))?;
1496        }
1497    }
1498
1499    let mut unstable_opts = false;
1500
1501    for dep in deps {
1502        if dep.unit.mode.is_run_custom_build() {
1503            cmd.env(
1504                "OUT_DIR",
1505                &build_runner.files().build_script_out_dir(&dep.unit),
1506            );
1507        }
1508    }
1509
1510    for arg in extern_args(build_runner, unit, &mut unstable_opts)? {
1511        cmd.arg(arg);
1512    }
1513
1514    for (var, env) in artifact::get_env(build_runner, deps)? {
1515        cmd.env(&var, env);
1516    }
1517
1518    // This will only be set if we're already using a feature
1519    // requiring nightly rust
1520    if unstable_opts {
1521        cmd.arg("-Z").arg("unstable-options");
1522    }
1523
1524    Ok(())
1525}
1526
1527/// Adds extra rustc flags and environment variables collected from the output
1528/// of a build-script to the command to execute, include custom environment
1529/// variables and `cfg`.
1530fn add_custom_flags(
1531    cmd: &mut ProcessBuilder,
1532    build_script_outputs: &BuildScriptOutputs,
1533    metadata: Option<UnitHash>,
1534) -> CargoResult<()> {
1535    if let Some(metadata) = metadata {
1536        if let Some(output) = build_script_outputs.get(metadata) {
1537            for cfg in output.cfgs.iter() {
1538                cmd.arg("--cfg").arg(cfg);
1539            }
1540            for check_cfg in &output.check_cfgs {
1541                cmd.arg("--check-cfg").arg(check_cfg);
1542            }
1543            for (name, value) in output.env.iter() {
1544                cmd.env(name, value);
1545            }
1546        }
1547    }
1548
1549    Ok(())
1550}
1551
1552/// Generates a list of `--extern` arguments.
1553pub fn extern_args(
1554    build_runner: &BuildRunner<'_, '_>,
1555    unit: &Unit,
1556    unstable_opts: &mut bool,
1557) -> CargoResult<Vec<OsString>> {
1558    let mut result = Vec::new();
1559    let deps = build_runner.unit_deps(unit);
1560
1561    // Closure to add one dependency to `result`.
1562    let mut link_to =
1563        |dep: &UnitDep, extern_crate_name: InternedString, noprelude: bool| -> CargoResult<()> {
1564            let mut value = OsString::new();
1565            let mut opts = Vec::new();
1566            let is_public_dependency_enabled = unit
1567                .pkg
1568                .manifest()
1569                .unstable_features()
1570                .require(Feature::public_dependency())
1571                .is_ok()
1572                || build_runner.bcx.gctx.cli_unstable().public_dependency;
1573            if !dep.public && unit.target.is_lib() && is_public_dependency_enabled {
1574                opts.push("priv");
1575                *unstable_opts = true;
1576            }
1577            if noprelude {
1578                opts.push("noprelude");
1579                *unstable_opts = true;
1580            }
1581            if !opts.is_empty() {
1582                value.push(opts.join(","));
1583                value.push(":");
1584            }
1585            value.push(extern_crate_name.as_str());
1586            value.push("=");
1587
1588            let mut pass = |file| {
1589                let mut value = value.clone();
1590                value.push(file);
1591                result.push(OsString::from("--extern"));
1592                result.push(value);
1593            };
1594
1595            let outputs = build_runner.outputs(&dep.unit)?;
1596
1597            if build_runner.only_requires_rmeta(unit, &dep.unit) || dep.unit.mode.is_check() {
1598                // Example: rlib dependency for an rlib, rmeta is all that is required.
1599                let output = outputs
1600                    .iter()
1601                    .find(|output| output.flavor == FileFlavor::Rmeta)
1602                    .expect("failed to find rmeta dep for pipelined dep");
1603                pass(&output.path);
1604            } else {
1605                // Example: a bin needs `rlib` for dependencies, it cannot use rmeta.
1606                for output in outputs.iter() {
1607                    if output.flavor == FileFlavor::Linkable {
1608                        pass(&output.path);
1609                    }
1610                }
1611            }
1612            Ok(())
1613        };
1614
1615    for dep in deps {
1616        if dep.unit.target.is_linkable() && !dep.unit.mode.is_doc() {
1617            link_to(dep, dep.extern_crate_name, dep.noprelude)?;
1618        }
1619    }
1620    if unit.target.proc_macro() {
1621        // Automatically import `proc_macro`.
1622        result.push(OsString::from("--extern"));
1623        result.push(OsString::from("proc_macro"));
1624    }
1625
1626    Ok(result)
1627}
1628
1629fn envify(s: &str) -> String {
1630    s.chars()
1631        .flat_map(|c| c.to_uppercase())
1632        .map(|c| if c == '-' { '_' } else { c })
1633        .collect()
1634}
1635
1636/// Configuration of the display of messages emitted by the compiler,
1637/// e.g. diagnostics, warnings, errors, and message caching.
1638struct OutputOptions {
1639    /// What format we're emitting from Cargo itself.
1640    format: MessageFormat,
1641    /// Where to write the JSON messages to support playback later if the unit
1642    /// is fresh. The file is created lazily so that in the normal case, lots
1643    /// of empty files are not created. If this is None, the output will not
1644    /// be cached (such as when replaying cached messages).
1645    cache_cell: Option<(PathBuf, LazyCell<File>)>,
1646    /// If `true`, display any diagnostics.
1647    /// Other types of JSON messages are processed regardless
1648    /// of the value of this flag.
1649    ///
1650    /// This is used primarily for cache replay. If you build with `-vv`, the
1651    /// cache will be filled with diagnostics from dependencies. When the
1652    /// cache is replayed without `-vv`, we don't want to show them.
1653    show_diagnostics: bool,
1654    /// Tracks the number of warnings we've seen so far.
1655    warnings_seen: usize,
1656    /// Tracks the number of errors we've seen so far.
1657    errors_seen: usize,
1658}
1659
1660impl OutputOptions {
1661    fn new(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> OutputOptions {
1662        let path = build_runner.files().message_cache_path(unit);
1663        // Remove old cache, ignore ENOENT, which is the common case.
1664        drop(fs::remove_file(&path));
1665        let cache_cell = Some((path, LazyCell::new()));
1666        let show_diagnostics =
1667            build_runner.bcx.gctx.warning_handling().unwrap_or_default() != WarningHandling::Allow;
1668        OutputOptions {
1669            format: build_runner.bcx.build_config.message_format,
1670            cache_cell,
1671            show_diagnostics,
1672            warnings_seen: 0,
1673            errors_seen: 0,
1674        }
1675    }
1676}
1677
1678fn on_stdout_line(
1679    state: &JobState<'_, '_>,
1680    line: &str,
1681    _package_id: PackageId,
1682    _target: &Target,
1683) -> CargoResult<()> {
1684    state.stdout(line.to_string())?;
1685    Ok(())
1686}
1687
1688fn on_stderr_line(
1689    state: &JobState<'_, '_>,
1690    line: &str,
1691    package_id: PackageId,
1692    manifest_path: &std::path::Path,
1693    target: &Target,
1694    options: &mut OutputOptions,
1695) -> CargoResult<()> {
1696    if on_stderr_line_inner(state, line, package_id, manifest_path, target, options)? {
1697        // Check if caching is enabled.
1698        if let Some((path, cell)) = &mut options.cache_cell {
1699            // Cache the output, which will be replayed later when Fresh.
1700            let f = cell.try_borrow_mut_with(|| paths::create(path))?;
1701            debug_assert!(!line.contains('\n'));
1702            f.write_all(line.as_bytes())?;
1703            f.write_all(&[b'\n'])?;
1704        }
1705    }
1706    Ok(())
1707}
1708
1709/// Returns true if the line should be cached.
1710fn on_stderr_line_inner(
1711    state: &JobState<'_, '_>,
1712    line: &str,
1713    package_id: PackageId,
1714    manifest_path: &std::path::Path,
1715    target: &Target,
1716    options: &mut OutputOptions,
1717) -> CargoResult<bool> {
1718    // We primarily want to use this function to process JSON messages from
1719    // rustc. The compiler should always print one JSON message per line, and
1720    // otherwise it may have other output intermingled (think RUST_LOG or
1721    // something like that), so skip over everything that doesn't look like a
1722    // JSON message.
1723    if !line.starts_with('{') {
1724        state.stderr(line.to_string())?;
1725        return Ok(true);
1726    }
1727
1728    let mut compiler_message: Box<serde_json::value::RawValue> = match serde_json::from_str(line) {
1729        Ok(msg) => msg,
1730
1731        // If the compiler produced a line that started with `{` but it wasn't
1732        // valid JSON, maybe it wasn't JSON in the first place! Forward it along
1733        // to stderr.
1734        Err(e) => {
1735            debug!("failed to parse json: {:?}", e);
1736            state.stderr(line.to_string())?;
1737            return Ok(true);
1738        }
1739    };
1740
1741    let count_diagnostic = |level, options: &mut OutputOptions| {
1742        if level == "warning" {
1743            options.warnings_seen += 1;
1744        } else if level == "error" {
1745            options.errors_seen += 1;
1746        }
1747    };
1748
1749    if let Ok(report) = serde_json::from_str::<FutureIncompatReport>(compiler_message.get()) {
1750        for item in &report.future_incompat_report {
1751            count_diagnostic(&*item.diagnostic.level, options);
1752        }
1753        state.future_incompat_report(report.future_incompat_report);
1754        return Ok(true);
1755    }
1756
1757    // Depending on what we're emitting from Cargo itself, we figure out what to
1758    // do with this JSON message.
1759    match options.format {
1760        // In the "human" output formats (human/short) or if diagnostic messages
1761        // from rustc aren't being included in the output of Cargo's JSON
1762        // messages then we extract the diagnostic (if present) here and handle
1763        // it ourselves.
1764        MessageFormat::Human
1765        | MessageFormat::Short
1766        | MessageFormat::Json {
1767            render_diagnostics: true,
1768            ..
1769        } => {
1770            #[derive(serde::Deserialize)]
1771            struct CompilerMessage<'a> {
1772                // `rendered` contains escape sequences, which can't be
1773                // zero-copy deserialized by serde_json.
1774                // See https://github.com/serde-rs/json/issues/742
1775                rendered: String,
1776                #[serde(borrow)]
1777                message: Cow<'a, str>,
1778                #[serde(borrow)]
1779                level: Cow<'a, str>,
1780                children: Vec<PartialDiagnostic>,
1781            }
1782
1783            // A partial rustfix::diagnostics::Diagnostic. We deserialize only a
1784            // subset of the fields because rustc's output can be extremely
1785            // deeply nested JSON in pathological cases involving macro
1786            // expansion. Rustfix's Diagnostic struct is recursive containing a
1787            // field `children: Vec<Self>`, and it can cause deserialization to
1788            // hit serde_json's default recursion limit, or overflow the stack
1789            // if we turn that off. Cargo only cares about the 1 field listed
1790            // here.
1791            #[derive(serde::Deserialize)]
1792            struct PartialDiagnostic {
1793                spans: Vec<PartialDiagnosticSpan>,
1794            }
1795
1796            // A partial rustfix::diagnostics::DiagnosticSpan.
1797            #[derive(serde::Deserialize)]
1798            struct PartialDiagnosticSpan {
1799                suggestion_applicability: Option<Applicability>,
1800            }
1801
1802            if let Ok(mut msg) = serde_json::from_str::<CompilerMessage<'_>>(compiler_message.get())
1803            {
1804                if msg.message.starts_with("aborting due to")
1805                    || msg.message.ends_with("warning emitted")
1806                    || msg.message.ends_with("warnings emitted")
1807                {
1808                    // Skip this line; we'll print our own summary at the end.
1809                    return Ok(true);
1810                }
1811                // state.stderr will add a newline
1812                if msg.rendered.ends_with('\n') {
1813                    msg.rendered.pop();
1814                }
1815                let rendered = msg.rendered;
1816                if options.show_diagnostics {
1817                    let machine_applicable: bool = msg
1818                        .children
1819                        .iter()
1820                        .map(|child| {
1821                            child
1822                                .spans
1823                                .iter()
1824                                .filter_map(|span| span.suggestion_applicability)
1825                                .any(|app| app == Applicability::MachineApplicable)
1826                        })
1827                        .any(|b| b);
1828                    count_diagnostic(&msg.level, options);
1829                    state.emit_diag(&msg.level, rendered, machine_applicable)?;
1830                }
1831                return Ok(true);
1832            }
1833        }
1834
1835        // Remove color information from the rendered string if color is not
1836        // enabled. Cargo always asks for ANSI colors from rustc. This allows
1837        // cached replay to enable/disable colors without re-invoking rustc.
1838        MessageFormat::Json { ansi: false, .. } => {
1839            #[derive(serde::Deserialize, serde::Serialize)]
1840            struct CompilerMessage<'a> {
1841                rendered: String,
1842                #[serde(flatten, borrow)]
1843                other: std::collections::BTreeMap<Cow<'a, str>, serde_json::Value>,
1844            }
1845            if let Ok(mut error) =
1846                serde_json::from_str::<CompilerMessage<'_>>(compiler_message.get())
1847            {
1848                error.rendered = anstream::adapter::strip_str(&error.rendered).to_string();
1849                let new_line = serde_json::to_string(&error)?;
1850                compiler_message = serde_json::value::RawValue::from_string(new_line)?;
1851            }
1852        }
1853
1854        // If ansi colors are desired then we should be good to go! We can just
1855        // pass through this message as-is.
1856        MessageFormat::Json { ansi: true, .. } => {}
1857    }
1858
1859    // We always tell rustc to emit messages about artifacts being produced.
1860    // These messages feed into pipelined compilation, as well as timing
1861    // information.
1862    //
1863    // Look for a matching directive and inform Cargo internally that a
1864    // metadata file has been produced.
1865    #[derive(serde::Deserialize)]
1866    struct ArtifactNotification<'a> {
1867        #[serde(borrow)]
1868        artifact: Cow<'a, str>,
1869    }
1870
1871    if let Ok(artifact) = serde_json::from_str::<ArtifactNotification<'_>>(compiler_message.get()) {
1872        trace!("found directive from rustc: `{}`", artifact.artifact);
1873        if artifact.artifact.ends_with(".rmeta") {
1874            debug!("looks like metadata finished early!");
1875            state.rmeta_produced();
1876        }
1877        return Ok(false);
1878    }
1879
1880    // And failing all that above we should have a legitimate JSON diagnostic
1881    // from the compiler, so wrap it in an external Cargo JSON message
1882    // indicating which package it came from and then emit it.
1883
1884    if !options.show_diagnostics {
1885        return Ok(true);
1886    }
1887
1888    #[derive(serde::Deserialize)]
1889    struct CompilerMessage<'a> {
1890        #[serde(borrow)]
1891        message: Cow<'a, str>,
1892        #[serde(borrow)]
1893        level: Cow<'a, str>,
1894    }
1895
1896    if let Ok(msg) = serde_json::from_str::<CompilerMessage<'_>>(compiler_message.get()) {
1897        if msg.message.starts_with("aborting due to")
1898            || msg.message.ends_with("warning emitted")
1899            || msg.message.ends_with("warnings emitted")
1900        {
1901            // Skip this line; we'll print our own summary at the end.
1902            return Ok(true);
1903        }
1904        count_diagnostic(&msg.level, options);
1905    }
1906
1907    let msg = machine_message::FromCompiler {
1908        package_id: package_id.to_spec(),
1909        manifest_path,
1910        target,
1911        message: compiler_message,
1912    }
1913    .to_json_string();
1914
1915    // Switch json lines from rustc/rustdoc that appear on stderr to stdout
1916    // instead. We want the stdout of Cargo to always be machine parseable as
1917    // stderr has our colorized human-readable messages.
1918    state.stdout(msg)?;
1919    Ok(true)
1920}
1921
1922/// Creates a unit of work that replays the cached compiler message.
1923///
1924/// Usually used when a job is fresh and doesn't need to recompile.
1925fn replay_output_cache(
1926    package_id: PackageId,
1927    manifest_path: PathBuf,
1928    target: &Target,
1929    path: PathBuf,
1930    format: MessageFormat,
1931    show_diagnostics: bool,
1932) -> Work {
1933    let target = target.clone();
1934    let mut options = OutputOptions {
1935        format,
1936        cache_cell: None,
1937        show_diagnostics,
1938        warnings_seen: 0,
1939        errors_seen: 0,
1940    };
1941    Work::new(move |state| {
1942        if !path.exists() {
1943            // No cached output, probably didn't emit anything.
1944            return Ok(());
1945        }
1946        // We sometimes have gigabytes of output from the compiler, so avoid
1947        // loading it all into memory at once, as that can cause OOM where
1948        // otherwise there would be none.
1949        let file = paths::open(&path)?;
1950        let mut reader = std::io::BufReader::new(file);
1951        let mut line = String::new();
1952        loop {
1953            let length = reader.read_line(&mut line)?;
1954            if length == 0 {
1955                break;
1956            }
1957            let trimmed = line.trim_end_matches(&['\n', '\r'][..]);
1958            on_stderr_line(
1959                state,
1960                trimmed,
1961                package_id,
1962                &manifest_path,
1963                &target,
1964                &mut options,
1965            )?;
1966            line.clear();
1967        }
1968        Ok(())
1969    })
1970}
1971
1972/// Provides a package name with descriptive target information,
1973/// e.g., '`foo` (bin "bar" test)', '`foo` (lib doctest)'.
1974fn descriptive_pkg_name(name: &str, target: &Target, mode: &CompileMode) -> String {
1975    let desc_name = target.description_named();
1976    let mode = if mode.is_rustc_test() && !(target.is_test() || target.is_bench()) {
1977        " test"
1978    } else if mode.is_doc_test() {
1979        " doctest"
1980    } else if mode.is_doc() {
1981        " doc"
1982    } else {
1983        ""
1984    };
1985    format!("`{name}` ({desc_name}{mode})")
1986}
1987
1988/// Applies environment variables from config `[env]` to [`ProcessBuilder`].
1989pub(crate) fn apply_env_config(
1990    gctx: &crate::GlobalContext,
1991    cmd: &mut ProcessBuilder,
1992) -> CargoResult<()> {
1993    for (key, value) in gctx.env_config()?.iter() {
1994        // never override a value that has already been set by cargo
1995        if cmd.get_envs().contains_key(key) {
1996            continue;
1997        }
1998        cmd.env(key, value);
1999    }
2000    Ok(())
2001}
2002
2003/// Checks if there are some scrape units waiting to be processed.
2004fn should_include_scrape_units(bcx: &BuildContext<'_, '_>, unit: &Unit) -> bool {
2005    unit.mode.is_doc() && bcx.scrape_units.len() > 0 && bcx.ws.unit_needs_doc_scrape(unit)
2006}
2007
2008/// Gets the file path of function call information output from `rustdoc`.
2009fn scrape_output_path(build_runner: &BuildRunner<'_, '_>, unit: &Unit) -> CargoResult<PathBuf> {
2010    assert!(unit.mode.is_doc() || unit.mode.is_doc_scrape());
2011    build_runner
2012        .outputs(unit)
2013        .map(|outputs| outputs[0].path.clone())
2014}