cargo/core/compiler/
compilation.rs

1//! Type definitions for the result of a compilation.
2
3use std::collections::{BTreeSet, HashMap};
4use std::ffi::{OsStr, OsString};
5use std::path::Path;
6use std::path::PathBuf;
7
8use cargo_platform::CfgExpr;
9use cargo_util::{ProcessBuilder, paths};
10
11use crate::core::Package;
12use crate::core::compiler::BuildContext;
13use crate::core::compiler::CompileTarget;
14use crate::core::compiler::RustdocFingerprint;
15use crate::core::compiler::apply_env_config;
16use crate::core::compiler::{CompileKind, Unit, UnitHash};
17use crate::util::{CargoResult, GlobalContext};
18
19/// Represents the kind of process we are creating.
20#[derive(Debug)]
21enum ToolKind {
22    /// See [`Compilation::rustc_process`].
23    Rustc,
24    /// See [`Compilation::rustdoc_process`].
25    Rustdoc,
26    /// See [`Compilation::host_process`].
27    HostProcess,
28    /// See [`Compilation::target_process`].
29    TargetProcess,
30}
31
32impl ToolKind {
33    fn is_rustc_tool(&self) -> bool {
34        matches!(self, ToolKind::Rustc | ToolKind::Rustdoc)
35    }
36}
37
38/// Structure with enough information to run `rustdoc --test`.
39pub struct Doctest {
40    /// What's being doctested
41    pub unit: Unit,
42    /// Arguments needed to pass to rustdoc to run this test.
43    pub args: Vec<OsString>,
44    /// Whether or not -Zunstable-options is needed.
45    pub unstable_opts: bool,
46    /// The -Clinker value to use.
47    pub linker: Option<PathBuf>,
48    /// The script metadata, if this unit's package has a build script.
49    ///
50    /// This is used for indexing [`Compilation::extra_env`].
51    pub script_metas: Option<Vec<UnitHash>>,
52
53    /// Environment variables to set in the rustdoc process.
54    pub env: HashMap<String, OsString>,
55}
56
57/// Information about the output of a unit.
58pub struct UnitOutput {
59    /// The unit that generated this output.
60    pub unit: Unit,
61    /// Path to the unit's primary output (an executable or cdylib).
62    pub path: PathBuf,
63    /// The script metadata, if this unit's package has a build script.
64    ///
65    /// This is used for indexing [`Compilation::extra_env`].
66    pub script_metas: Option<Vec<UnitHash>>,
67
68    /// Environment variables to set in the unit's process.
69    pub env: HashMap<String, OsString>,
70}
71
72/// A structure returning the result of a compilation.
73pub struct Compilation<'gctx> {
74    /// An array of all tests created during this compilation.
75    pub tests: Vec<UnitOutput>,
76
77    /// An array of all binaries created.
78    pub binaries: Vec<UnitOutput>,
79
80    /// An array of all cdylibs created.
81    pub cdylibs: Vec<UnitOutput>,
82
83    /// The crate names of the root units specified on the command-line.
84    pub root_crate_names: Vec<String>,
85
86    /// All directories for the output of native build commands.
87    ///
88    /// This is currently used to drive some entries which are added to the
89    /// `LD_LIBRARY_PATH` as appropriate.
90    ///
91    /// The order should be deterministic.
92    pub native_dirs: BTreeSet<PathBuf>,
93
94    /// Root output directory (for the local package's artifacts)
95    pub root_output: HashMap<CompileKind, PathBuf>,
96
97    /// Output directories for rust dependencies.
98    /// May be for the host or for a specific target.
99    pub deps_output: HashMap<CompileKind, BTreeSet<PathBuf>>,
100
101    /// The path to libstd for each target
102    sysroot_target_libdir: HashMap<CompileKind, PathBuf>,
103
104    /// Extra environment variables that were passed to compilations and should
105    /// be passed to future invocations of programs.
106    ///
107    /// The key is the build script metadata for uniquely identifying the
108    /// `RunCustomBuild` unit that generated these env vars.
109    pub extra_env: HashMap<UnitHash, Vec<(String, String)>>,
110
111    /// Libraries to test with rustdoc.
112    pub to_doc_test: Vec<Doctest>,
113
114    /// Rustdoc fingerprint files to determine whether we need to run `rustdoc --merge=finalize`.
115    ///
116    /// See `-Zrustdoc-mergeable-info` for more.
117    pub rustdoc_fingerprints: Option<HashMap<CompileKind, RustdocFingerprint>>,
118
119    /// The target host triple.
120    pub host: String,
121
122    gctx: &'gctx GlobalContext,
123
124    /// Rustc process to be used by default
125    rustc_process: ProcessBuilder,
126    /// Rustc process to be used for workspace crates instead of `rustc_process`
127    rustc_workspace_wrapper_process: ProcessBuilder,
128    /// Optional rustc process to be used for primary crates instead of either `rustc_process` or
129    /// `rustc_workspace_wrapper_process`
130    primary_rustc_process: Option<ProcessBuilder>,
131
132    /// The runner to use for each host or target process.
133    runners: HashMap<CompileKind, Option<(PathBuf, Vec<String>)>>,
134    /// The linker to use for each host or target.
135    linkers: HashMap<CompileKind, Option<PathBuf>>,
136
137    /// The total number of lint warnings emitted by the compilation.
138    pub lint_warning_count: usize,
139}
140
141impl<'gctx> Compilation<'gctx> {
142    pub fn new<'a>(bcx: &BuildContext<'a, 'gctx>) -> CargoResult<Compilation<'gctx>> {
143        let rustc_process = bcx.rustc().process();
144        let primary_rustc_process = bcx.build_config.primary_unit_rustc.clone();
145        let rustc_workspace_wrapper_process = bcx.rustc().workspace_process();
146        let host = bcx.host_triple().to_string();
147
148        // When `target-applies-to-host=false`, and without `--target`,
149        // there will be only `CompileKind::Host` in requested_kinds.
150        // Need to insert target config explicitly for target-applies-to-host=false
151        // to find the correct configs.
152        let insert_explicit_host_runner = !bcx.gctx.target_applies_to_host()?
153            && bcx
154                .build_config
155                .requested_kinds
156                .iter()
157                .any(CompileKind::is_host);
158        let mut runners = bcx
159            .build_config
160            .requested_kinds
161            .iter()
162            .chain(Some(&CompileKind::Host))
163            .map(|kind| Ok((*kind, target_runner(bcx, *kind)?)))
164            .collect::<CargoResult<HashMap<_, _>>>()?;
165        if insert_explicit_host_runner {
166            let kind = explicit_host_kind(&host);
167            runners.insert(kind, target_runner(bcx, kind)?);
168        }
169
170        let mut linkers = bcx
171            .build_config
172            .requested_kinds
173            .iter()
174            .chain(Some(&CompileKind::Host))
175            .map(|kind| Ok((*kind, target_linker(bcx, *kind)?)))
176            .collect::<CargoResult<HashMap<_, _>>>()?;
177        if insert_explicit_host_runner {
178            let kind = explicit_host_kind(&host);
179            linkers.insert(kind, target_linker(bcx, kind)?);
180        }
181        Ok(Compilation {
182            native_dirs: BTreeSet::new(),
183            root_output: HashMap::new(),
184            deps_output: HashMap::new(),
185            sysroot_target_libdir: get_sysroot_target_libdir(bcx)?,
186            tests: Vec::new(),
187            binaries: Vec::new(),
188            cdylibs: Vec::new(),
189            root_crate_names: Vec::new(),
190            extra_env: HashMap::new(),
191            to_doc_test: Vec::new(),
192            rustdoc_fingerprints: None,
193            gctx: bcx.gctx,
194            host,
195            rustc_process,
196            rustc_workspace_wrapper_process,
197            primary_rustc_process,
198            runners,
199            linkers,
200            lint_warning_count: 0,
201        })
202    }
203
204    /// Returns a [`ProcessBuilder`] for running `rustc`.
205    ///
206    /// `is_primary` is true if this is a "primary package", which means it
207    /// was selected by the user on the command-line (such as with a `-p`
208    /// flag), see [`crate::core::compiler::BuildRunner::primary_packages`].
209    ///
210    /// `is_workspace` is true if this is a workspace member.
211    pub fn rustc_process(
212        &self,
213        unit: &Unit,
214        is_primary: bool,
215        is_workspace: bool,
216    ) -> CargoResult<ProcessBuilder> {
217        let mut rustc = if is_primary && self.primary_rustc_process.is_some() {
218            self.primary_rustc_process.clone().unwrap()
219        } else if is_workspace {
220            self.rustc_workspace_wrapper_process.clone()
221        } else {
222            self.rustc_process.clone()
223        };
224        if self.gctx.extra_verbose() {
225            rustc.display_env_vars();
226        }
227        let cmd = fill_rustc_tool_env(rustc, unit);
228        self.fill_env(cmd, &unit.pkg, None, unit.kind, ToolKind::Rustc)
229    }
230
231    /// Returns a [`ProcessBuilder`] for running `rustdoc`.
232    pub fn rustdoc_process(
233        &self,
234        unit: &Unit,
235        script_metas: Option<&Vec<UnitHash>>,
236    ) -> CargoResult<ProcessBuilder> {
237        let mut rustdoc = ProcessBuilder::new(&*self.gctx.rustdoc()?);
238        if self.gctx.extra_verbose() {
239            rustdoc.display_env_vars();
240        }
241        let cmd = fill_rustc_tool_env(rustdoc, unit);
242        let mut cmd = self.fill_env(cmd, &unit.pkg, script_metas, unit.kind, ToolKind::Rustdoc)?;
243        cmd.retry_with_argfile(true);
244        unit.target.edition().cmd_edition_arg(&mut cmd);
245
246        for crate_type in unit.target.rustc_crate_types() {
247            cmd.arg("--crate-type").arg(crate_type.as_str());
248        }
249
250        Ok(cmd)
251    }
252
253    /// Returns a [`ProcessBuilder`] appropriate for running a process for the
254    /// host platform.
255    ///
256    /// This is currently only used for running build scripts. If you use this
257    /// for anything else, please be extra careful on how environment
258    /// variables are set!
259    pub fn host_process<T: AsRef<OsStr>>(
260        &self,
261        cmd: T,
262        pkg: &Package,
263    ) -> CargoResult<ProcessBuilder> {
264        // Only use host runner when -Zhost-config is enabled
265        // to ensure `target.<host>.runner` does not wrap build scripts.
266        let builder = if !self.gctx.target_applies_to_host()?
267            && let Some((runner, args)) = self
268                .runners
269                .get(&CompileKind::Host)
270                .and_then(|x| x.as_ref())
271        {
272            let mut builder = ProcessBuilder::new(runner);
273            builder.args(args);
274            builder.arg(cmd);
275            builder
276        } else {
277            ProcessBuilder::new(cmd)
278        };
279        self.fill_env(builder, pkg, None, CompileKind::Host, ToolKind::HostProcess)
280    }
281
282    pub fn target_runner(&self, kind: CompileKind) -> Option<&(PathBuf, Vec<String>)> {
283        let target_applies_to_host = self.gctx.target_applies_to_host().unwrap_or(true);
284        let kind = if !target_applies_to_host && kind.is_host() {
285            // Use explicit host target triple when `target-applies-to-host=false`
286            // This ensures `host.runner` won't be accidentally applied to `cargo run` / `cargo test`.
287            explicit_host_kind(&self.host)
288        } else {
289            kind
290        };
291        self.runners.get(&kind).and_then(|x| x.as_ref())
292    }
293
294    /// Gets the `[host.linker]` for host build target (build scripts and proc macros).
295    pub fn host_linker(&self) -> Option<&Path> {
296        self.linkers
297            .get(&CompileKind::Host)
298            .and_then(|x| x.as_ref())
299            .map(|x| x.as_path())
300    }
301
302    /// Gets the user-specified linker for a particular host or target.
303    pub fn target_linker(&self, kind: CompileKind) -> Option<&Path> {
304        let target_applies_to_host = self.gctx.target_applies_to_host().unwrap_or(true);
305        let kind = if !target_applies_to_host && kind.is_host() {
306            // Use explicit host target triple when `target-applies-to-host=false`
307            // This ensures `host.linker` won't be accidentally applied to normal builds
308            explicit_host_kind(&self.host)
309        } else {
310            kind
311        };
312        self.linkers
313            .get(&kind)
314            .and_then(|x| x.as_ref())
315            .map(|x| x.as_path())
316    }
317
318    /// Returns a [`ProcessBuilder`] appropriate for running a process for the
319    /// target platform. This is typically used for `cargo run` and `cargo
320    /// test`.
321    ///
322    /// `script_metas` is the metadata for the `RunCustomBuild` unit that this
323    /// unit used for its build script. Use `None` if the package did not have
324    /// a build script.
325    pub fn target_process<T: AsRef<OsStr>>(
326        &self,
327        cmd: T,
328        kind: CompileKind,
329        pkg: &Package,
330        script_metas: Option<&Vec<UnitHash>>,
331    ) -> CargoResult<ProcessBuilder> {
332        let builder = if let Some((runner, args)) = self.target_runner(kind) {
333            let mut builder = ProcessBuilder::new(runner);
334            builder.args(args);
335            builder.arg(cmd);
336            builder
337        } else {
338            ProcessBuilder::new(cmd)
339        };
340        let tool_kind = ToolKind::TargetProcess;
341        let mut builder = self.fill_env(builder, pkg, script_metas, kind, tool_kind)?;
342
343        if let Some(client) = self.gctx.jobserver_from_env() {
344            builder.inherit_jobserver(client);
345        }
346
347        Ok(builder)
348    }
349
350    /// Prepares a new process with an appropriate environment to run against
351    /// the artifacts produced by the build process.
352    ///
353    /// The package argument is also used to configure environment variables as
354    /// well as the working directory of the child process.
355    fn fill_env(
356        &self,
357        mut cmd: ProcessBuilder,
358        pkg: &Package,
359        script_metas: Option<&Vec<UnitHash>>,
360        kind: CompileKind,
361        tool_kind: ToolKind,
362    ) -> CargoResult<ProcessBuilder> {
363        let mut search_path = Vec::new();
364        if tool_kind.is_rustc_tool() {
365            if matches!(tool_kind, ToolKind::Rustdoc) {
366                // HACK: `rustdoc --test` not only compiles but executes doctests.
367                // Ideally only execution phase should have search paths appended,
368                // so the executions can find native libs just like other tests.
369                // However, there is no way to separate these two phase, so this
370                // hack is added for both phases.
371                // TODO: handle doctest-xcompile
372                search_path.extend(super::filter_dynamic_search_path(
373                    self.native_dirs.iter(),
374                    &self.root_output[&CompileKind::Host],
375                ));
376            }
377            if let Some(paths) = self.deps_output.get(&CompileKind::Host) {
378                search_path.extend(paths.clone());
379            }
380        } else {
381            if let Some(path) = self.root_output.get(&kind) {
382                search_path.extend(super::filter_dynamic_search_path(
383                    self.native_dirs.iter(),
384                    path,
385                ));
386                search_path.push(path.clone());
387            }
388            if let Some(paths) = self.deps_output.get(&kind) {
389                search_path.extend(paths.clone());
390            }
391            // For build-std, we don't want to accidentally pull in any shared
392            // libs from the sysroot that ships with rustc. This may not be
393            // required (at least I cannot craft a situation where it
394            // matters), but is here to be safe.
395            if self.gctx.cli_unstable().build_std.is_none() ||
396                // Proc macros dynamically link to std, so set it anyway.
397                pkg.proc_macro()
398            {
399                search_path.push(self.sysroot_target_libdir[&kind].clone());
400            }
401        }
402
403        let dylib_path = paths::dylib_path();
404        let dylib_path_is_empty = dylib_path.is_empty();
405        if dylib_path.starts_with(&search_path) {
406            search_path = dylib_path;
407        } else {
408            search_path.extend(dylib_path.into_iter());
409        }
410        if cfg!(target_os = "macos") && dylib_path_is_empty {
411            // These are the defaults when DYLD_FALLBACK_LIBRARY_PATH isn't
412            // set or set to an empty string. Since Cargo is explicitly setting
413            // the value, make sure the defaults still work.
414            if let Some(home) = self.gctx.get_env_os("HOME") {
415                search_path.push(PathBuf::from(home).join("lib"));
416            }
417            search_path.push(PathBuf::from("/usr/local/lib"));
418            search_path.push(PathBuf::from("/usr/lib"));
419        }
420        let search_path = paths::join_paths(&search_path, paths::dylib_path_envvar())?;
421
422        cmd.env(paths::dylib_path_envvar(), &search_path);
423        if let Some(meta_vec) = script_metas {
424            for meta in meta_vec {
425                if let Some(env) = self.extra_env.get(meta) {
426                    for (k, v) in env {
427                        cmd.env(k, v);
428                    }
429                }
430            }
431        }
432
433        let cargo_exe = self.gctx.cargo_exe()?;
434        cmd.env(crate::CARGO_ENV, cargo_exe);
435
436        // When adding new environment variables depending on
437        // crate properties which might require rebuild upon change
438        // consider adding the corresponding properties to the hash
439        // in BuildContext::target_metadata()
440        cmd.env("CARGO_MANIFEST_DIR", pkg.root())
441            .env("CARGO_MANIFEST_PATH", pkg.manifest_path())
442            .env("CARGO_PKG_VERSION_MAJOR", &pkg.version().major.to_string())
443            .env("CARGO_PKG_VERSION_MINOR", &pkg.version().minor.to_string())
444            .env("CARGO_PKG_VERSION_PATCH", &pkg.version().patch.to_string())
445            .env("CARGO_PKG_VERSION_PRE", pkg.version().pre.as_str())
446            .env("CARGO_PKG_VERSION", &pkg.version().to_string())
447            .env("CARGO_PKG_NAME", &*pkg.name());
448
449        for (key, value) in pkg.manifest().metadata().env_vars() {
450            cmd.env(key, value.as_ref());
451        }
452
453        cmd.cwd(pkg.root());
454
455        apply_env_config(self.gctx, &mut cmd)?;
456
457        Ok(cmd)
458    }
459}
460
461/// Prepares a `rustc_tool` process with additional environment variables
462/// that are only relevant in a context that has a unit
463fn fill_rustc_tool_env(mut cmd: ProcessBuilder, unit: &Unit) -> ProcessBuilder {
464    if unit.target.is_executable() {
465        let name = unit
466            .target
467            .binary_filename()
468            .unwrap_or(unit.target.name().to_string());
469
470        cmd.env("CARGO_BIN_NAME", name);
471    }
472    cmd.env("CARGO_CRATE_NAME", unit.target.crate_name());
473    cmd
474}
475
476fn get_sysroot_target_libdir(
477    bcx: &BuildContext<'_, '_>,
478) -> CargoResult<HashMap<CompileKind, PathBuf>> {
479    bcx.all_kinds
480        .iter()
481        .map(|&kind| {
482            let Some(info) = bcx.target_data.get_info(kind) else {
483                let target = match kind {
484                    CompileKind::Host => "host".to_owned(),
485                    CompileKind::Target(s) => s.short_name().to_owned(),
486                };
487
488                let dependency = bcx
489                    .unit_graph
490                    .iter()
491                    .find_map(|(u, _)| (u.kind == kind).then_some(u.pkg.summary().package_id()))
492                    .unwrap();
493
494                anyhow::bail!(
495                    "could not find specification for target `{target}`.\n  \
496                    Dependency `{dependency}` requires to build for target `{target}`."
497                )
498            };
499
500            Ok((kind, info.sysroot_target_libdir.clone()))
501        })
502        .collect()
503}
504
505fn target_runner(
506    bcx: &BuildContext<'_, '_>,
507    kind: CompileKind,
508) -> CargoResult<Option<(PathBuf, Vec<String>)>> {
509    if let Some(runner) = bcx.target_data.target_config(kind).runner.as_ref() {
510        let path = runner.val.path.clone().resolve_program(bcx.gctx);
511        return Ok(Some((path, runner.val.args.clone())));
512    }
513
514    // With `target-applies-to-host = true`,
515    // host artifacts must fall through to pick up from [target]
516    // since this is the stable behavior
517    if kind.is_host() && !bcx.gctx.target_applies_to_host()? {
518        return Ok(None);
519    }
520
521    // try target.'cfg(...)'.runner
522    let target_cfg = bcx.target_data.info(kind).cfg();
523    let mut cfgs = bcx
524        .gctx
525        .target_cfgs()?
526        .iter()
527        .filter_map(|(key, cfg)| cfg.runner.as_ref().map(|runner| (key, runner)))
528        .filter(|(key, _runner)| CfgExpr::matches_key(key, target_cfg));
529    let matching_runner = cfgs.next();
530    if let Some((key, runner)) = cfgs.next() {
531        anyhow::bail!(
532            "several matching instances of `target.'cfg(..)'.runner` in configurations\n\
533             first match `{}` located in {}\n\
534             second match `{}` located in {}",
535            matching_runner.unwrap().0,
536            matching_runner.unwrap().1.definition,
537            key,
538            runner.definition
539        );
540    }
541    Ok(matching_runner.map(|(_k, runner)| {
542        (
543            runner.val.path.clone().resolve_program(bcx.gctx),
544            runner.val.args.clone(),
545        )
546    }))
547}
548
549/// Gets the user-specified linker for a particular host or target from the configuration.
550fn target_linker(bcx: &BuildContext<'_, '_>, kind: CompileKind) -> CargoResult<Option<PathBuf>> {
551    // Try host.linker and target.{}.linker.
552    if let Some(path) = bcx
553        .target_data
554        .target_config(kind)
555        .linker
556        .as_ref()
557        .map(|l| l.val.clone().resolve_program(bcx.gctx))
558    {
559        return Ok(Some(path));
560    }
561
562    // With `target-applies-to-host = true`,
563    // host artifacts must fall through to pick up from [target]
564    // since this is the stable behavior
565    if kind.is_host() && !bcx.gctx.target_applies_to_host()? {
566        return Ok(None);
567    }
568
569    // Try target.'cfg(...)'.linker.
570    let target_cfg = bcx.target_data.info(kind).cfg();
571    let mut cfgs = bcx
572        .gctx
573        .target_cfgs()?
574        .iter()
575        .filter_map(|(key, cfg)| cfg.linker.as_ref().map(|linker| (key, linker)))
576        .filter(|(key, _linker)| CfgExpr::matches_key(key, target_cfg));
577    let matching_linker = cfgs.next();
578    if let Some((key, linker)) = cfgs.next() {
579        anyhow::bail!(
580            "several matching instances of `target.'cfg(..)'.linker` in configurations\n\
581             first match `{}` located in {}\n\
582             second match `{}` located in {}",
583            matching_linker.unwrap().0,
584            matching_linker.unwrap().1.definition,
585            key,
586            linker.definition
587        );
588    }
589    Ok(matching_linker.map(|(_k, linker)| linker.val.clone().resolve_program(bcx.gctx)))
590}
591
592fn explicit_host_kind(host: &str) -> CompileKind {
593    let target = CompileTarget::new(host, false).expect("must be a host tuple");
594    CompileKind::Target(target)
595}
cargo/core/compiler/compilation.rs

cargo/core/compiler/
compilation.rs
