#
cargo/core/compiler/build_runner/
compilation_files.rs

    1//! See [`CompilationFiles`].
    2
    3use std::collections::HashMap;
    4use std::fmt;
    5use std::hash::{Hash, Hasher};
    6use std::path::{Path, PathBuf};
    7use std::sync::Arc;
    8
    9use lazycell::LazyCell;
    10use tracing::debug;
    11
    12use super::{BuildContext, BuildRunner, CompileKind, FileFlavor, Layout};
    13use crate::core::compiler::{CompileMode, CompileTarget, CrateType, FileType, Unit};
    14use crate::core::{Target, TargetKind, Workspace};
    15use crate::util::{self, CargoResult, StableHasher};
    16
    17/// This is a generic version number that can be changed to make
    18/// backwards-incompatible changes to any file structures in the output
    19/// directory. For example, the fingerprint files or the build-script
    20/// output files.
    21///
    22/// Normally cargo updates ship with rustc updates which will
    23/// cause a new hash due to the rustc version changing, but this allows
    24/// cargo to be extra careful to deal with different versions of cargo that
    25/// use the same rustc version.
    26const METADATA_VERSION: u8 = 2;
    27
    28/// Uniquely identify a [`Unit`] under specific circumstances, see [`Metadata`] for more.
    29#[derive(Copy, Clone, Hash, Eq, PartialEq, Ord, PartialOrd)]
    30pub struct UnitHash(u64);
    31
    32impl fmt::Display for UnitHash {
    33    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    34        write!(f, "{:016x}", self.0)
    35    }
    36}
    37
    38impl fmt::Debug for UnitHash {
    39    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    40        write!(f, "UnitHash({:016x})", self.0)
    41    }
    42}
    43
    44/// [`Metadata`] tracks several [`UnitHash`]s, including
    45/// [`Metadata::unit_id`], [`Metadata::c_metadata`], and [`Metadata::c_extra_filename`].
    46///
    47/// We use a hash because it is an easy way to guarantee
    48/// that all the inputs can be converted to a valid path.
    49///
    50/// [`Metadata::unit_id`] is used to uniquely identify a unit in the build graph.
    51/// This serves as a similar role as [`Metadata::c_extra_filename`] in that it uniquely identifies output
    52/// on the filesystem except that its always present.
    53///
    54/// [`Metadata::c_extra_filename`] is needed for cases like:
    55/// - A project may depend on crate `A` and crate `B`, so the package name must be in the file name.
    56/// - Similarly a project may depend on two versions of `A`, so the version must be in the file name.
    57///
    58/// This also acts as the main layer of caching provided by Cargo
    59/// so this must include all things that need to be distinguished in different parts of
    60/// the same build. This is absolutely required or we override things before
    61/// we get chance to use them.
    62///
    63/// For example, we want to cache `cargo build` and `cargo doc` separately, so that running one
    64/// does not invalidate the artifacts for the other. We do this by including [`CompileMode`] in the
    65/// hash, thus the artifacts go in different folders and do not override each other.
    66/// If we don't add something that we should have, for this reason, we get the
    67/// correct output but rebuild more than is needed.
    68///
    69/// Some things that need to be tracked to ensure the correct output should definitely *not*
    70/// go in the `Metadata`. For example, the modification time of a file, should be tracked to make a
    71/// rebuild when the file changes. However, it would be wasteful to include in the `Metadata`. The
    72/// old artifacts are never going to be needed again. We can save space by just overwriting them.
    73/// If we add something that we should not have, for this reason, we get the correct output but take
    74/// more space than needed. This makes not including something in `Metadata`
    75/// a form of cache invalidation.
    76///
    77/// Note that the `Fingerprint` is in charge of tracking everything needed to determine if a
    78/// rebuild is needed.
    79///
    80/// [`Metadata::c_metadata`] is used for symbol mangling, because if you have two versions of
    81/// the same crate linked together, their symbols need to be differentiated.
    82///
    83/// You should avoid anything that would interfere with reproducible
    84/// builds. For example, *any* absolute path should be avoided. This is one
    85/// reason that `RUSTFLAGS` is not in [`Metadata::c_metadata`], because it often has
    86/// absolute paths (like `--remap-path-prefix` which is fundamentally used for
    87/// reproducible builds and has absolute paths in it). Also, in some cases the
    88/// mangled symbols need to be stable between different builds with different
    89/// settings. For example, profile-guided optimizations need to swap
    90/// `RUSTFLAGS` between runs, but needs to keep the same symbol names.
    91#[derive(Copy, Clone, Debug)]
    92pub struct Metadata {
    93    unit_id: UnitHash,
    94    c_metadata: UnitHash,
    95    c_extra_filename: Option<UnitHash>,
    96}
    97
    98impl Metadata {
    99    /// A hash to identify a given [`Unit`] in the build graph
    100    pub fn unit_id(&self) -> UnitHash {
    101        self.unit_id
    102    }
    103
    104    /// A hash to add to symbol naming through `-C metadata`
    105    pub fn c_metadata(&self) -> UnitHash {
    106        self.c_metadata
    107    }
    108
    109    /// A hash to add to file names through `-C extra-filename`
    110    pub fn c_extra_filename(&self) -> Option<UnitHash> {
    111        self.c_extra_filename
    112    }
    113}
    114
    115/// Collection of information about the files emitted by the compiler, and the
    116/// output directory structure.
    117pub struct CompilationFiles<'a, 'gctx> {
    118    /// The target directory layout for the host (and target if it is the same as host).
    119    pub(super) host: Layout,
    120    /// The target directory layout for the target (if different from then host).
    121    pub(super) target: HashMap<CompileTarget, Layout>,
    122    /// Additional directory to include a copy of the outputs.
    123    export_dir: Option<PathBuf>,
    124    /// The root targets requested by the user on the command line (does not
    125    /// include dependencies).
    126    roots: Vec<Unit>,
    127    ws: &'a Workspace<'gctx>,
    128    /// Metadata hash to use for each unit.
    129    metas: HashMap<Unit, Metadata>,
    130    /// For each Unit, a list all files produced.
    131    outputs: HashMap<Unit, LazyCell<Arc<Vec<OutputFile>>>>,
    132}
    133
    134/// Info about a single file emitted by the compiler.
    135#[derive(Debug)]
    136pub struct OutputFile {
    137    /// Absolute path to the file that will be produced by the build process.
    138    pub path: PathBuf,
    139    /// If it should be linked into `target`, and what it should be called
    140    /// (e.g., without metadata).
    141    pub hardlink: Option<PathBuf>,
    142    /// If `--artifact-dir` is specified, the absolute path to the exported file.
    143    pub export_path: Option<PathBuf>,
    144    /// Type of the file (library / debug symbol / else).
    145    pub flavor: FileFlavor,
    146}
    147
    148impl OutputFile {
    149    /// Gets the hard link if present; otherwise, returns the path.
    150    pub fn bin_dst(&self) -> &PathBuf {
    151        match self.hardlink {
    152            Some(ref link_dst) => link_dst,
    153            None => &self.path,
    154        }
    155    }
    156}
    157
    158impl<'a, 'gctx: 'a> CompilationFiles<'a, 'gctx> {
    159    pub(super) fn new(
    160        build_runner: &BuildRunner<'a, 'gctx>,
    161        host: Layout,
    162        target: HashMap<CompileTarget, Layout>,
    163    ) -> CompilationFiles<'a, 'gctx> {
    164        let mut metas = HashMap::new();
    165        for unit in &build_runner.bcx.roots {
    166            metadata_of(unit, build_runner, &mut metas);
    167        }
    168        let outputs = metas
    169            .keys()
    170            .cloned()
    171            .map(|unit| (unit, LazyCell::new()))
    172            .collect();
    173        CompilationFiles {
    174            ws: build_runner.bcx.ws,
    175            host,
    176            target,
    177            export_dir: build_runner.bcx.build_config.export_dir.clone(),
    178            roots: build_runner.bcx.roots.clone(),
    179            metas,
    180            outputs,
    181        }
    182    }
    183
    184    /// Returns the appropriate directory layout for either a plugin or not.
    185    pub fn layout(&self, kind: CompileKind) -> &Layout {
    186        match kind {
    187            CompileKind::Host => &self.host,
    188            CompileKind::Target(target) => &self.target[&target],
    189        }
    190    }
    191
    192    /// Gets the metadata for the given unit.
    193    ///
    194    /// See [`Metadata`] and [`fingerprint`] module for more.
    195    ///
    196    /// [`fingerprint`]: super::super::fingerprint#fingerprints-and-metadata
    197    pub fn metadata(&self, unit: &Unit) -> Metadata {
    198        self.metas[unit]
    199    }
    200
    201    /// Gets the short hash based only on the `PackageId`.
    202    /// Used for the metadata when `c_extra_filename` returns `None`.
    203    fn target_short_hash(&self, unit: &Unit) -> String {
    204        let hashable = unit.pkg.package_id().stable_hash(self.ws.root());
    205        util::short_hash(&(METADATA_VERSION, hashable))
    206    }
    207
    208    /// Returns the directory where the artifacts for the given unit are
    209    /// initially created.
    210    pub fn out_dir(&self, unit: &Unit) -> PathBuf {
    211        // Docscrape units need to have doc/ set as the out_dir so sources for reverse-dependencies
    212        // will be put into doc/ and not into deps/ where the *.examples files are stored.
    213        if unit.mode.is_doc() || unit.mode.is_doc_scrape() {
    214            self.layout(unit.kind).doc().to_path_buf()
    215        } else if unit.mode.is_doc_test() {
    216            panic!("doc tests do not have an out dir");
    217        } else if unit.target.is_custom_build() {
    218            self.build_script_dir(unit)
    219        } else if unit.target.is_example() {
    220            self.layout(unit.kind).build_examples().to_path_buf()
    221        } else if unit.artifact.is_true() {
    222            self.artifact_dir(unit)
    223        } else {
    224            self.deps_dir(unit).to_path_buf()
    225        }
    226    }
    227
    228    /// Additional export directory from `--artifact-dir`.
    229    pub fn export_dir(&self) -> Option<PathBuf> {
    230        self.export_dir.clone()
    231    }
    232
    233    /// Directory name to use for a package in the form `NAME-HASH`.
    234    ///
    235    /// Note that some units may share the same directory, so care should be
    236    /// taken in those cases!
    237    fn pkg_dir(&self, unit: &Unit) -> String {
    238        let name = unit.pkg.package_id().name();
    239        let meta = self.metas[unit];
    240        if let Some(c_extra_filename) = meta.c_extra_filename() {
    241            format!("{}-{}", name, c_extra_filename)
    242        } else {
    243            format!("{}-{}", name, self.target_short_hash(unit))
    244        }
    245    }
    246
    247    /// Returns the final artifact path for the host (`/…/target/debug`)
    248    pub fn host_dest(&self) -> &Path {
    249        self.host.dest()
    250    }
    251
    252    /// Returns the root of the build output tree for the host (`/…/target`)
    253    pub fn host_root(&self) -> &Path {
    254        self.host.root()
    255    }
    256
    257    /// Returns the host `deps` directory path.
    258    pub fn host_deps(&self) -> &Path {
    259        self.host.deps()
    260    }
    261
    262    /// Returns the directories where Rust crate dependencies are found for the
    263    /// specified unit.
    264    pub fn deps_dir(&self, unit: &Unit) -> &Path {
    265        self.layout(unit.kind).deps()
    266    }
    267
    268    /// Directory where the fingerprint for the given unit should go.
    269    pub fn fingerprint_dir(&self, unit: &Unit) -> PathBuf {
    270        let dir = self.pkg_dir(unit);
    271        self.layout(unit.kind).fingerprint().join(dir)
    272    }
    273
    274    /// Returns the path for a file in the fingerprint directory.
    275    ///
    276    /// The "prefix" should be something to distinguish the file from other
    277    /// files in the fingerprint directory.
    278    pub fn fingerprint_file_path(&self, unit: &Unit, prefix: &str) -> PathBuf {
    279        // Different targets need to be distinguished in the
    280        let kind = unit.target.kind().description();
    281        let flavor = if unit.mode.is_any_test() {
    282            "test-"
    283        } else if unit.mode.is_doc() {
    284            "doc-"
    285        } else if unit.mode.is_run_custom_build() {
    286            "run-"
    287        } else {
    288            ""
    289        };
    290        let name = format!("{}{}{}-{}", prefix, flavor, kind, unit.target.name());
    291        self.fingerprint_dir(unit).join(name)
    292    }
    293
    294    /// Path where compiler output is cached.
    295    pub fn message_cache_path(&self, unit: &Unit) -> PathBuf {
    296        self.fingerprint_file_path(unit, "output-")
    297    }
    298
    299    /// Returns the directory where a compiled build script is stored.
    300    /// `/path/to/target/{debug,release}/build/PKG-HASH`
    301    pub fn build_script_dir(&self, unit: &Unit) -> PathBuf {
    302        assert!(unit.target.is_custom_build());
    303        assert!(!unit.mode.is_run_custom_build());
    304        assert!(self.metas.contains_key(unit));
    305        let dir = self.pkg_dir(unit);
    306        self.layout(CompileKind::Host).build().join(dir)
    307    }
    308
    309    /// Returns the directory for compiled artifacts files.
    310    /// `/path/to/target/{debug,release}/deps/artifact/KIND/PKG-HASH`
    311    fn artifact_dir(&self, unit: &Unit) -> PathBuf {
    312        assert!(self.metas.contains_key(unit));
    313        assert!(unit.artifact.is_true());
    314        let dir = self.pkg_dir(unit);
    315        let kind = match unit.target.kind() {
    316            TargetKind::Bin => "bin",
    317            TargetKind::Lib(lib_kinds) => match lib_kinds.as_slice() {
    318                &[CrateType::Cdylib] => "cdylib",
    319                &[CrateType::Staticlib] => "staticlib",
    320                invalid => unreachable!(
    321                    "BUG: unexpected artifact library type(s): {:?} - these should have been split",
    322                    invalid
    323                ),
    324            },
    325            invalid => unreachable!(
    326                "BUG: {:?} are not supposed to be used as artifacts",
    327                invalid
    328            ),
    329        };
    330        self.layout(unit.kind).artifact().join(dir).join(kind)
    331    }
    332
    333    /// Returns the directory where information about running a build script
    334    /// is stored.
    335    /// `/path/to/target/{debug,release}/build/PKG-HASH`
    336    pub fn build_script_run_dir(&self, unit: &Unit) -> PathBuf {
    337        assert!(unit.target.is_custom_build());
    338        assert!(unit.mode.is_run_custom_build());
    339        let dir = self.pkg_dir(unit);
    340        self.layout(unit.kind).build().join(dir)
    341    }
    342
    343    /// Returns the "`OUT_DIR`" directory for running a build script.
    344    /// `/path/to/target/{debug,release}/build/PKG-HASH/out`
    345    pub fn build_script_out_dir(&self, unit: &Unit) -> PathBuf {
    346        self.build_script_run_dir(unit).join("out")
    347    }
    348
    349    /// Returns the path to the executable binary for the given bin target.
    350    ///
    351    /// This should only to be used when a `Unit` is not available.
    352    pub fn bin_link_for_target(
    353        &self,
    354        target: &Target,
    355        kind: CompileKind,
    356        bcx: &BuildContext<'_, '_>,
    357    ) -> CargoResult<PathBuf> {
    358        assert!(target.is_bin());
    359        let dest = self.layout(kind).dest();
    360        let info = bcx.target_data.info(kind);
    361        let (file_types, _) = info
    362            .rustc_outputs(
    363                CompileMode::Build,
    364                &TargetKind::Bin,
    365                bcx.target_data.short_name(&kind),
    366                bcx.gctx,
    367            )
    368            .expect("target must support `bin`");
    369
    370        let file_type = file_types
    371            .iter()
    372            .find(|file_type| file_type.flavor == FileFlavor::Normal)
    373            .expect("target must support `bin`");
    374
    375        Ok(dest.join(file_type.uplift_filename(target)))
    376    }
    377
    378    /// Returns the filenames that the given unit will generate.
    379    ///
    380    /// Note: It is not guaranteed that all of the files will be generated.
    381    pub(super) fn outputs(
    382        &self,
    383        unit: &Unit,
    384        bcx: &BuildContext<'a, 'gctx>,
    385    ) -> CargoResult<Arc<Vec<OutputFile>>> {
    386        self.outputs[unit]
    387            .try_borrow_with(|| self.calc_outputs(unit, bcx))
    388            .map(Arc::clone)
    389    }
    390
    391    /// Returns the path where the output for the given unit and `FileType`
    392    /// should be uplifted to.
    393    ///
    394    /// Returns `None` if the unit shouldn't be uplifted (for example, a
    395    /// dependent rlib).
    396    fn uplift_to(&self, unit: &Unit, file_type: &FileType, from_path: &Path) -> Option<PathBuf> {
    397        // Tests, check, doc, etc. should not be uplifted.
    398        if unit.mode != CompileMode::Build || file_type.flavor == FileFlavor::Rmeta {
    399            return None;
    400        }
    401
    402        // Artifact dependencies are never uplifted.
    403        if unit.artifact.is_true() {
    404            return None;
    405        }
    406
    407        // - Binaries: The user always wants to see these, even if they are
    408        //   implicitly built (for example for integration tests).
    409        // - dylibs: This ensures that the dynamic linker pulls in all the
    410        //   latest copies (even if the dylib was built from a previous cargo
    411        //   build). There are complex reasons for this, see #8139, #6167, #6162.
    412        // - Things directly requested from the command-line (the "roots").
    413        //   This one is a little questionable for rlibs (see #6131), but is
    414        //   historically how Cargo has operated. This is primarily useful to
    415        //   give the user access to staticlibs and cdylibs.
    416        if !unit.target.is_bin()
    417            && !unit.target.is_custom_build()
    418            && file_type.crate_type != Some(CrateType::Dylib)
    419            && !self.roots.contains(unit)
    420        {
    421            return None;
    422        }
    423
    424        let filename = file_type.uplift_filename(&unit.target);
    425        let uplift_path = if unit.target.is_example() {
    426            // Examples live in their own little world.
    427            self.layout(unit.kind).examples().join(filename)
    428        } else if unit.target.is_custom_build() {
    429            self.build_script_dir(unit).join(filename)
    430        } else {
    431            self.layout(unit.kind).dest().join(filename)
    432        };
    433        if from_path == uplift_path {
    434            // This can happen with things like examples that reside in the
    435            // same directory, do not have a metadata hash (like on Windows),
    436            // and do not have hyphens.
    437            return None;
    438        }
    439        Some(uplift_path)
    440    }
    441
    442    /// Calculates the filenames that the given unit will generate.
    443    /// Should use [`CompilationFiles::outputs`] instead
    444    /// as it caches the result of this function.
    445    fn calc_outputs(
    446        &self,
    447        unit: &Unit,
    448        bcx: &BuildContext<'a, 'gctx>,
    449    ) -> CargoResult<Arc<Vec<OutputFile>>> {
    450        let ret = match unit.mode {
    451            _ if unit.skip_non_compile_time_dep => {
    452                // This skips compilations so no outputs
    453                vec![]
    454            }
    455            CompileMode::Doc => {
    456                let path = if bcx.build_config.intent.wants_doc_json_output() {
    457                    self.out_dir(unit)
    458                        .join(format!("{}.json", unit.target.crate_name()))
    459                } else {
    460                    self.out_dir(unit)
    461                        .join(unit.target.crate_name())
    462                        .join("index.html")
    463                };
    464
    465                vec![OutputFile {
    466                    path,
    467                    hardlink: None,
    468                    export_path: None,
    469                    flavor: FileFlavor::Normal,
    470                }]
    471            }
    472            CompileMode::RunCustomBuild => {
    473                // At this time, this code path does not handle build script
    474                // outputs.
    475                vec![]
    476            }
    477            CompileMode::Doctest => {
    478                // Doctests are built in a temporary directory and then
    479                // deleted. There is the `--persist-doctests` unstable flag,
    480                // but Cargo does not know about that.
    481                vec![]
    482            }
    483            CompileMode::Docscrape => {
    484                // The file name needs to be stable across Cargo sessions.
    485                // This originally used unit.buildkey(), but that isn't stable,
    486                // so we use metadata instead (prefixed with name for debugging).
    487                let file_name = format!(
    488                    "{}-{}.examples",
    489                    unit.pkg.name(),
    490                    self.metadata(unit).unit_id()
    491                );
    492                let path = self.deps_dir(unit).join(file_name);
    493                vec![OutputFile {
    494                    path,
    495                    hardlink: None,
    496                    export_path: None,
    497                    flavor: FileFlavor::Normal,
    498                }]
    499            }
    500            CompileMode::Test | CompileMode::Build | CompileMode::Check { .. } => {
    501                let mut outputs = self.calc_outputs_rustc(unit, bcx)?;
    502                if bcx.build_config.sbom && bcx.gctx.cli_unstable().sbom {
    503                    let sbom_files: Vec<_> = outputs
    504                        .iter()
    505                        .filter(|o| matches!(o.flavor, FileFlavor::Normal | FileFlavor::Linkable))
    506                        .map(|output| OutputFile {
    507                            path: Self::append_sbom_suffix(&output.path),
    508                            hardlink: output.hardlink.as_ref().map(Self::append_sbom_suffix),
    509                            export_path: output.export_path.as_ref().map(Self::append_sbom_suffix),
    510                            flavor: FileFlavor::Sbom,
    511                        })
    512                        .collect();
    513                    outputs.extend(sbom_files.into_iter());
    514                }
    515                outputs
    516            }
    517        };
    518        debug!("Target filenames: {:?}", ret);
    519
    520        Ok(Arc::new(ret))
    521    }
    522
    523    /// Append the SBOM suffix to the file name.
    524    fn append_sbom_suffix(link: &PathBuf) -> PathBuf {
    525        const SBOM_FILE_EXTENSION: &str = ".cargo-sbom.json";
    526        let mut link_buf = link.clone().into_os_string();
    527        link_buf.push(SBOM_FILE_EXTENSION);
    528        PathBuf::from(link_buf)
    529    }
    530
    531    /// Computes the actual, full pathnames for all the files generated by rustc.
    532    ///
    533    /// The `OutputFile` also contains the paths where those files should be
    534    /// "uplifted" to.
    535    fn calc_outputs_rustc(
    536        &self,
    537        unit: &Unit,
    538        bcx: &BuildContext<'a, 'gctx>,
    539    ) -> CargoResult<Vec<OutputFile>> {
    540        let out_dir = self.out_dir(unit);
    541
    542        let info = bcx.target_data.info(unit.kind);
    543        let triple = bcx.target_data.short_name(&unit.kind);
    544        let (file_types, unsupported) =
    545            info.rustc_outputs(unit.mode, unit.target.kind(), triple, bcx.gctx)?;
    546        if file_types.is_empty() {
    547            if !unsupported.is_empty() {
    548                let unsupported_strs: Vec<_> = unsupported.iter().map(|ct| ct.as_str()).collect();
    549                anyhow::bail!(
    550                    "cannot produce {} for `{}` as the target `{}` \
    551                     does not support these crate types",
    552                    unsupported_strs.join(", "),
    553                    unit.pkg,
    554                    triple,
    555                )
    556            }
    557            anyhow::bail!(
    558                "cannot compile `{}` as the target `{}` does not \
    559                 support any of the output crate types",
    560                unit.pkg,
    561                triple,
    562            );
    563        }
    564
    565        // Convert FileType to OutputFile.
    566        let mut outputs = Vec::new();
    567        for file_type in file_types {
    568            let meta = self.metas[unit];
    569            let meta_opt = meta.c_extra_filename().map(|h| h.to_string());
    570            let path = out_dir.join(file_type.output_filename(&unit.target, meta_opt.as_deref()));
    571
    572            // If, the `different_binary_name` feature is enabled, the name of the hardlink will
    573            // be the name of the binary provided by the user in `Cargo.toml`.
    574            let hardlink = self.uplift_to(unit, &file_type, &path);
    575            let export_path = if unit.target.is_custom_build() {
    576                None
    577            } else {
    578                self.export_dir.as_ref().and_then(|export_dir| {
    579                    hardlink
    580                        .as_ref()
    581                        .map(|hardlink| export_dir.join(hardlink.file_name().unwrap()))
    582                })
    583            };
    584            outputs.push(OutputFile {
    585                path,
    586                hardlink,
    587                export_path,
    588                flavor: file_type.flavor,
    589            });
    590        }
    591        Ok(outputs)
    592    }
    593}
    594
    595/// Gets the metadata hash for the given [`Unit`].
    596///
    597/// When a metadata hash doesn't exist for the given unit,
    598/// this calls itself recursively to compute metadata hashes of all its dependencies.
    599/// See [`compute_metadata`] for how a single metadata hash is computed.
    600fn metadata_of<'a>(
    601    unit: &Unit,
    602    build_runner: &BuildRunner<'_, '_>,
    603    metas: &'a mut HashMap<Unit, Metadata>,
    604) -> &'a Metadata {
    605    if !metas.contains_key(unit) {
    606        let meta = compute_metadata(unit, build_runner, metas);
    607        metas.insert(unit.clone(), meta);
    608        for dep in build_runner.unit_deps(unit) {
    609            metadata_of(&dep.unit, build_runner, metas);
    610        }
    611    }
    612    &metas[unit]
    613}
    614
    615/// Computes the metadata hash for the given [`Unit`].
    616fn compute_metadata(
    617    unit: &Unit,
    618    build_runner: &BuildRunner<'_, '_>,
    619    metas: &mut HashMap<Unit, Metadata>,
    620) -> Metadata {
    621    let bcx = &build_runner.bcx;
    622    let deps_metadata = build_runner
    623        .unit_deps(unit)
    624        .iter()
    625        .map(|dep| *metadata_of(&dep.unit, build_runner, metas))
    626        .collect::<Vec<_>>();
    627    let use_extra_filename = use_extra_filename(bcx, unit);
    628
    629    let mut shared_hasher = StableHasher::new();
    630
    631    METADATA_VERSION.hash(&mut shared_hasher);
    632
    633    let ws_root = if unit.is_std {
    634        // SourceId for stdlib crates is an absolute path inside the sysroot.
    635        // Pass the sysroot as workspace root so that we hash a relative path.
    636        // This avoids the metadata hash changing depending on where the user installed rustc.
    637        &bcx.target_data.get_info(unit.kind).unwrap().sysroot
    638    } else {
    639        bcx.ws.root()
    640    };
    641
    642    // Unique metadata per (name, source, version) triple. This'll allow us
    643    // to pull crates from anywhere without worrying about conflicts.
    644    unit.pkg
    645        .package_id()
    646        .stable_hash(ws_root)
    647        .hash(&mut shared_hasher);
    648
    649    // Also mix in enabled features to our metadata. This'll ensure that
    650    // when changing feature sets each lib is separately cached.
    651    unit.features.hash(&mut shared_hasher);
    652
    653    // Throw in the profile we're compiling with. This helps caching
    654    // `panic=abort` and `panic=unwind` artifacts, additionally with various
    655    // settings like debuginfo and whatnot.
    656    unit.profile.hash(&mut shared_hasher);
    657    unit.mode.hash(&mut shared_hasher);
    658    build_runner.lto[unit].hash(&mut shared_hasher);
    659
    660    // Artifacts compiled for the host should have a different
    661    // metadata piece than those compiled for the target, so make sure
    662    // we throw in the unit's `kind` as well.  Use `fingerprint_hash`
    663    // so that the StableHash doesn't change based on the pathnames
    664    // of the custom target JSON spec files.
    665    unit.kind.fingerprint_hash().hash(&mut shared_hasher);
    666
    667    // Finally throw in the target name/kind. This ensures that concurrent
    668    // compiles of targets in the same crate don't collide.
    669    unit.target.name().hash(&mut shared_hasher);
    670    unit.target.kind().hash(&mut shared_hasher);
    671
    672    hash_rustc_version(bcx, &mut shared_hasher, unit);
    673
    674    if build_runner.bcx.ws.is_member(&unit.pkg) {
    675        // This is primarily here for clippy. This ensures that the clippy
    676        // artifacts are separate from the `check` ones.
    677        if let Some(path) = &build_runner.bcx.rustc().workspace_wrapper {
    678            path.hash(&mut shared_hasher);
    679        }
    680    }
    681
    682    // Seed the contents of `__CARGO_DEFAULT_LIB_METADATA` to the hasher if present.
    683    // This should be the release channel, to get a different hash for each channel.
    684    if let Ok(ref channel) = build_runner
    685        .bcx
    686        .gctx
    687        .get_env("__CARGO_DEFAULT_LIB_METADATA")
    688    {
    689        channel.hash(&mut shared_hasher);
    690    }
    691
    692    // std units need to be kept separate from user dependencies. std crates
    693    // are differentiated in the Unit with `is_std` (for things like
    694    // `-Zforce-unstable-if-unmarked`), so they are always built separately.
    695    // This isn't strictly necessary for build dependencies which probably
    696    // don't need unstable support. A future experiment might be to set
    697    // `is_std` to false for build dependencies so that they can be shared
    698    // with user dependencies.
    699    unit.is_std.hash(&mut shared_hasher);
    700
    701    // While we don't hash RUSTFLAGS because it may contain absolute paths that
    702    // hurts reproducibility, we track whether a unit's RUSTFLAGS is from host
    703    // config, so that we can generate a different metadata hash for runtime
    704    // and compile-time units.
    705    //
    706    // HACK: This is a temporary hack for fixing rust-lang/cargo#14253
    707    // Need to find a long-term solution to replace this fragile workaround.
    708    // See https://github.com/rust-lang/cargo/pull/14432#discussion_r1725065350
    709    if unit.kind.is_host() && !bcx.gctx.target_applies_to_host().unwrap_or_default() {
    710        let host_info = bcx.target_data.info(CompileKind::Host);
    711        let target_configs_are_different = unit.rustflags != host_info.rustflags
    712            || unit.rustdocflags != host_info.rustdocflags
    713            || bcx
    714                .target_data
    715                .target_config(CompileKind::Host)
    716                .links_overrides
    717                != unit.links_overrides;
    718        target_configs_are_different.hash(&mut shared_hasher);
    719    }
    720
    721    let mut c_metadata_hasher = shared_hasher.clone();
    722    // Mix in the target-metadata of all the dependencies of this target.
    723    let mut dep_c_metadata_hashes = deps_metadata
    724        .iter()
    725        .map(|m| m.c_metadata)
    726        .collect::<Vec<_>>();
    727    dep_c_metadata_hashes.sort();
    728    dep_c_metadata_hashes.hash(&mut c_metadata_hasher);
    729
    730    let mut c_extra_filename_hasher = shared_hasher.clone();
    731    // Mix in the target-metadata of all the dependencies of this target.
    732    let mut dep_c_extra_filename_hashes = deps_metadata
    733        .iter()
    734        .map(|m| m.c_extra_filename)
    735        .collect::<Vec<_>>();
    736    dep_c_extra_filename_hashes.sort();
    737    dep_c_extra_filename_hashes.hash(&mut c_extra_filename_hasher);
    738    // Avoid trashing the caches on RUSTFLAGS changing via `c_extra_filename`
    739    //
    740    // Limited to `c_extra_filename` to help with reproducible build / PGO issues.
    741    let default = Vec::new();
    742    let extra_args = build_runner.bcx.extra_args_for(unit).unwrap_or(&default);
    743    if !has_remap_path_prefix(&extra_args) {
    744        extra_args.hash(&mut c_extra_filename_hasher);
    745    }
    746    if unit.mode.is_doc() || unit.mode.is_doc_scrape() {
    747        if !has_remap_path_prefix(&unit.rustdocflags) {
    748            unit.rustdocflags.hash(&mut c_extra_filename_hasher);
    749        }
    750    } else {
    751        if !has_remap_path_prefix(&unit.rustflags) {
    752            unit.rustflags.hash(&mut c_extra_filename_hasher);
    753        }
    754    }
    755
    756    let c_metadata = UnitHash(Hasher::finish(&c_metadata_hasher));
    757    let c_extra_filename = UnitHash(Hasher::finish(&c_extra_filename_hasher));
    758    let unit_id = c_extra_filename;
    759
    760    let c_extra_filename = use_extra_filename.then_some(c_extra_filename);
    761
    762    Metadata {
    763        unit_id,
    764        c_metadata,
    765        c_extra_filename,
    766    }
    767}
    768
    769/// HACK: Detect the *potential* presence of `--remap-path-prefix`
    770///
    771/// As CLI parsing is contextual and dependent on the CLI definition to understand the context, we
    772/// can't say for sure whether `--remap-path-prefix` is present, so we guess if anything looks like
    773/// it.
    774/// If we could, we'd strip it out for hashing.
    775/// Instead, we use this to avoid hashing rustflags if it might be present to avoid the risk of taking
    776/// a flag that is trying to make things reproducible and making things less reproducible by the
    777/// `-Cextra-filename` showing up in the rlib, even with `split-debuginfo`.
    778fn has_remap_path_prefix(args: &[String]) -> bool {
    779    args.iter()
    780        .any(|s| s.starts_with("--remap-path-prefix=") || s == "--remap-path-prefix")
    781}
    782
    783/// Hash the version of rustc being used during the build process.
    784fn hash_rustc_version(bcx: &BuildContext<'_, '_>, hasher: &mut StableHasher, unit: &Unit) {
    785    let vers = &bcx.rustc().version;
    786    if vers.pre.is_empty() || bcx.gctx.cli_unstable().separate_nightlies {
    787        // For stable, keep the artifacts separate. This helps if someone is
    788        // testing multiple versions, to avoid recompiles. Note though that for
    789        // cross-compiled builds the `host:` line of `verbose_version` is
    790        // omitted since rustc should produce the same output for each target
    791        // regardless of the host.
    792        for line in bcx.rustc().verbose_version.lines() {
    793            if unit.kind.is_host() || !line.starts_with("host: ") {
    794                line.hash(hasher);
    795            }
    796        }
    797        return;
    798    }
    799    // On "nightly"/"beta"/"dev"/etc, keep each "channel" separate. Don't hash
    800    // the date/git information, so that whenever someone updates "nightly",
    801    // they won't have a bunch of stale artifacts in the target directory.
    802    //
    803    // This assumes that the first segment is the important bit ("nightly",
    804    // "beta", "dev", etc.). Skip other parts like the `.3` in `-beta.3`.
    805    vers.pre.split('.').next().hash(hasher);
    806    // Keep "host" since some people switch hosts to implicitly change
    807    // targets, (like gnu vs musl or gnu vs msvc). In the future, we may want
    808    // to consider hashing `unit.kind.short_name()` instead.
    809    if unit.kind.is_host() {
    810        bcx.rustc().host.hash(hasher);
    811    }
    812    // None of the other lines are important. Currently they are:
    813    // binary: rustc  <-- or "rustdoc"
    814    // commit-hash: 38114ff16e7856f98b2b4be7ab4cd29b38bed59a
    815    // commit-date: 2020-03-21
    816    // host: x86_64-apple-darwin
    817    // release: 1.44.0-nightly
    818    // LLVM version: 9.0
    819    //
    820    // The backend version ("LLVM version") might become more relevant in
    821    // the future when cranelift sees more use, and people want to switch
    822    // between different backends without recompiling.
    823}
    824
    825/// Returns whether or not this unit should use a hash in the filename to make it unique.
    826fn use_extra_filename(bcx: &BuildContext<'_, '_>, unit: &Unit) -> bool {
    827    if unit.mode.is_doc_test() || unit.mode.is_doc() {
    828        // Doc tests do not have metadata.
    829        return false;
    830    }
    831    if unit.mode.is_any_test() || unit.mode.is_check() {
    832        // These always use metadata.
    833        return true;
    834    }
    835    // No metadata in these cases:
    836    //
    837    // - dylibs:
    838    //   - if any dylib names are encoded in executables, so they can't be renamed.
    839    //   - TODO: Maybe use `-install-name` on macOS or `-soname` on other UNIX systems
    840    //     to specify the dylib name to be used by the linker instead of the filename.
    841    // - Windows MSVC executables: The path to the PDB is embedded in the
    842    //   executable, and we don't want the PDB path to include the hash in it.
    843    // - wasm32-unknown-emscripten executables: When using emscripten, the path to the
    844    //   .wasm file is embedded in the .js file, so we don't want the hash in there.
    845    //
    846    // This is only done for local packages, as we don't expect to export
    847    // dependencies.
    848    //
    849    // The __CARGO_DEFAULT_LIB_METADATA env var is used to override this to
    850    // force metadata in the hash. This is only used for building libstd. For
    851    // example, if libstd is placed in a common location, we don't want a file
    852    // named /usr/lib/libstd.so which could conflict with other rustc
    853    // installs. In addition it prevents accidentally loading a libstd of a
    854    // different compiler at runtime.
    855    // See https://github.com/rust-lang/cargo/issues/3005
    856    let short_name = bcx.target_data.short_name(&unit.kind);
    857    if (unit.target.is_dylib()
    858        || unit.target.is_cdylib()
    859        || (unit.target.is_executable() && short_name == "wasm32-unknown-emscripten")
    860        || (unit.target.is_executable() && short_name.contains("msvc")))
    861        && unit.pkg.package_id().source_id().is_path()
    862        && bcx.gctx.get_env("__CARGO_DEFAULT_LIB_METADATA").is_err()
    863    {
    864        return false;
    865    }
    866    true
    867}