cargo/core/compiler/build_runner/
mod.rs

Help
1//! [`BuildRunner`] is the mutable state used during the build process.
2
3use std::collections::{BTreeSet, HashMap, HashSet};
4use std::path::{Path, PathBuf};
5use std::sync::{Arc, Mutex};
6
7use crate::core::compiler::compilation::{self, UnitOutput};
8use crate::core::compiler::{self, artifact, Unit};
9use crate::core::PackageId;
10use crate::util::cache_lock::CacheLockMode;
11use crate::util::errors::CargoResult;
12use anyhow::{bail, Context as _};
13use filetime::FileTime;
14use itertools::Itertools;
15use jobserver::Client;
16
17use super::build_plan::BuildPlan;
18use super::custom_build::{self, BuildDeps, BuildScriptOutputs, BuildScripts};
19use super::fingerprint::{Checksum, Fingerprint};
20use super::job_queue::JobQueue;
21use super::layout::Layout;
22use super::lto::Lto;
23use super::unit_graph::UnitDep;
24use super::{
25    BuildContext, Compilation, CompileKind, CompileMode, Executor, FileFlavor, RustDocFingerprint,
26};
27
28mod compilation_files;
29use self::compilation_files::CompilationFiles;
30pub use self::compilation_files::{Metadata, OutputFile, UnitHash};
31
32/// Collection of all the stuff that is needed to perform a build.
33///
34/// Different from the [`BuildContext`], `Context` is a _mutable_ state used
35/// throughout the entire build process. Everything is coordinated through this.
36///
37/// [`BuildContext`]: crate::core::compiler::BuildContext
38pub struct BuildRunner<'a, 'gctx> {
39    /// Mostly static information about the build task.
40    pub bcx: &'a BuildContext<'a, 'gctx>,
41    /// A large collection of information about the result of the entire compilation.
42    pub compilation: Compilation<'gctx>,
43    /// Output from build scripts, updated after each build script runs.
44    pub build_script_outputs: Arc<Mutex<BuildScriptOutputs>>,
45    /// Dependencies (like rerun-if-changed) declared by a build script.
46    /// This is *only* populated from the output from previous runs.
47    /// If the build script hasn't ever been run, then it must be run.
48    pub build_explicit_deps: HashMap<Unit, BuildDeps>,
49    /// Fingerprints used to detect if a unit is out-of-date.
50    pub fingerprints: HashMap<Unit, Arc<Fingerprint>>,
51    /// Cache of file mtimes to reduce filesystem hits.
52    pub mtime_cache: HashMap<PathBuf, FileTime>,
53    /// Cache of file checksums to reduce filesystem reads.
54    pub checksum_cache: HashMap<PathBuf, Checksum>,
55    /// A set used to track which units have been compiled.
56    /// A unit may appear in the job graph multiple times as a dependency of
57    /// multiple packages, but it only needs to run once.
58    pub compiled: HashSet<Unit>,
59    /// Linking information for each `Unit`.
60    /// See `build_map` for details.
61    pub build_scripts: HashMap<Unit, Arc<BuildScripts>>,
62    /// Job server client to manage concurrency with other processes.
63    pub jobserver: Client,
64    /// "Primary" packages are the ones the user selected on the command-line
65    /// with `-p` flags. If no flags are specified, then it is the defaults
66    /// based on the current directory and the default workspace members.
67    primary_packages: HashSet<PackageId>,
68    /// An abstraction of the files and directories that will be generated by
69    /// the compilation. This is `None` until after `unit_dependencies` has
70    /// been computed.
71    files: Option<CompilationFiles<'a, 'gctx>>,
72
73    /// A set of units which are compiling rlibs and are expected to produce
74    /// metadata files in addition to the rlib itself.
75    rmeta_required: HashSet<Unit>,
76
77    /// Map of the LTO-status of each unit. This indicates what sort of
78    /// compilation is happening (only object, only bitcode, both, etc), and is
79    /// precalculated early on.
80    pub lto: HashMap<Unit, Lto>,
81
82    /// Map of Doc/Docscrape units to metadata for their -Cmetadata flag.
83    /// See `Context::find_metadata_units` for more details.
84    pub metadata_for_doc_units: HashMap<Unit, Metadata>,
85
86    /// Set of metadata of Docscrape units that fail before completion, e.g.
87    /// because the target has a type error. This is in an Arc<Mutex<..>>
88    /// because it is continuously updated as the job progresses.
89    pub failed_scrape_units: Arc<Mutex<HashSet<UnitHash>>>,
90}
91
92impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
93    pub fn new(bcx: &'a BuildContext<'a, 'gctx>) -> CargoResult<Self> {
94        // Load up the jobserver that we'll use to manage our parallelism. This
95        // is the same as the GNU make implementation of a jobserver, and
96        // intentionally so! It's hoped that we can interact with GNU make and
97        // all share the same jobserver.
98        //
99        // Note that if we don't have a jobserver in our environment then we
100        // create our own, and we create it with `n` tokens, but immediately
101        // acquire one, because one token is ourself, a running process.
102        let jobserver = match bcx.gctx.jobserver_from_env() {
103            Some(c) => c.clone(),
104            None => {
105                let client =
106                    Client::new(bcx.jobs() as usize).context("failed to create jobserver")?;
107                client.acquire_raw()?;
108                client
109            }
110        };
111
112        Ok(Self {
113            bcx,
114            compilation: Compilation::new(bcx)?,
115            build_script_outputs: Arc::new(Mutex::new(BuildScriptOutputs::default())),
116            fingerprints: HashMap::new(),
117            mtime_cache: HashMap::new(),
118            checksum_cache: HashMap::new(),
119            compiled: HashSet::new(),
120            build_scripts: HashMap::new(),
121            build_explicit_deps: HashMap::new(),
122            jobserver,
123            primary_packages: HashSet::new(),
124            files: None,
125            rmeta_required: HashSet::new(),
126            lto: HashMap::new(),
127            metadata_for_doc_units: HashMap::new(),
128            failed_scrape_units: Arc::new(Mutex::new(HashSet::new())),
129        })
130    }
131
132    /// Dry-run the compilation without actually running it.
133    ///
134    /// This is expected to collect information like the location of output artifacts.
135    /// Please keep in sync with non-compilation part in [`BuildRunner::compile`].
136    pub fn dry_run(mut self) -> CargoResult<Compilation<'gctx>> {
137        let _lock = self
138            .bcx
139            .gctx
140            .acquire_package_cache_lock(CacheLockMode::Shared)?;
141        self.lto = super::lto::generate(self.bcx)?;
142        self.prepare_units()?;
143        self.prepare()?;
144        self.check_collisions()?;
145
146        for unit in &self.bcx.roots {
147            self.collect_tests_and_executables(unit)?;
148        }
149
150        Ok(self.compilation)
151    }
152
153    /// Starts compilation, waits for it to finish, and returns information
154    /// about the result of compilation.
155    ///
156    /// See [`ops::cargo_compile`] for a higher-level view of the compile process.
157    ///
158    /// [`ops::cargo_compile`]: crate::ops::cargo_compile
159    #[tracing::instrument(skip_all)]
160    pub fn compile(mut self, exec: &Arc<dyn Executor>) -> CargoResult<Compilation<'gctx>> {
161        // A shared lock is held during the duration of the build since rustc
162        // needs to read from the `src` cache, and we don't want other
163        // commands modifying the `src` cache while it is running.
164        let _lock = self
165            .bcx
166            .gctx
167            .acquire_package_cache_lock(CacheLockMode::Shared)?;
168        let mut queue = JobQueue::new(self.bcx);
169        let mut plan = BuildPlan::new();
170        let build_plan = self.bcx.build_config.build_plan;
171        self.lto = super::lto::generate(self.bcx)?;
172        self.prepare_units()?;
173        self.prepare()?;
174        custom_build::build_map(&mut self)?;
175        self.check_collisions()?;
176        self.compute_metadata_for_doc_units();
177
178        // We need to make sure that if there were any previous docs
179        // already compiled, they were compiled with the same Rustc version that we're currently
180        // using. Otherwise we must remove the `doc/` folder and compile again forcing a rebuild.
181        //
182        // This is important because the `.js`/`.html` & `.css` files that are generated by Rustc don't have
183        // any versioning (See https://github.com/rust-lang/cargo/issues/8461).
184        // Therefore, we can end up with weird bugs and behaviours if we mix different
185        // versions of these files.
186        if self.bcx.build_config.mode.is_doc() {
187            RustDocFingerprint::check_rustdoc_fingerprint(&self)?
188        }
189
190        for unit in &self.bcx.roots {
191            let force_rebuild = self.bcx.build_config.force_rebuild;
192            super::compile(&mut self, &mut queue, &mut plan, unit, exec, force_rebuild)?;
193        }
194
195        // Now that we've got the full job queue and we've done all our
196        // fingerprint analysis to determine what to run, bust all the memoized
197        // fingerprint hashes to ensure that during the build they all get the
198        // most up-to-date values. In theory we only need to bust hashes that
199        // transitively depend on a dirty build script, but it shouldn't matter
200        // that much for performance anyway.
201        for fingerprint in self.fingerprints.values() {
202            fingerprint.clear_memoized();
203        }
204
205        // Now that we've figured out everything that we're going to do, do it!
206        queue.execute(&mut self, &mut plan)?;
207
208        if build_plan {
209            plan.set_inputs(self.build_plan_inputs()?);
210            plan.output_plan(self.bcx.gctx);
211        }
212
213        // Add `OUT_DIR` to env vars if unit has a build script.
214        let units_with_build_script = &self
215            .bcx
216            .roots
217            .iter()
218            .filter(|unit| self.build_scripts.contains_key(unit))
219            .dedup_by(|x, y| x.pkg.package_id() == y.pkg.package_id())
220            .collect::<Vec<_>>();
221        for unit in units_with_build_script {
222            for dep in &self.bcx.unit_graph[unit] {
223                if dep.unit.mode.is_run_custom_build() {
224                    let out_dir = self
225                        .files()
226                        .build_script_out_dir(&dep.unit)
227                        .display()
228                        .to_string();
229                    let script_meta = self.get_run_build_script_metadata(&dep.unit);
230                    self.compilation
231                        .extra_env
232                        .entry(script_meta)
233                        .or_insert_with(Vec::new)
234                        .push(("OUT_DIR".to_string(), out_dir));
235                }
236            }
237        }
238
239        // Collect the result of the build into `self.compilation`.
240        for unit in &self.bcx.roots {
241            self.collect_tests_and_executables(unit)?;
242
243            // Collect information for `rustdoc --test`.
244            if unit.mode.is_doc_test() {
245                let mut unstable_opts = false;
246                let mut args = compiler::extern_args(&self, unit, &mut unstable_opts)?;
247                args.extend(compiler::lto_args(&self, unit));
248                args.extend(compiler::features_args(unit));
249                args.extend(compiler::check_cfg_args(unit));
250
251                let script_meta = self.find_build_script_metadata(unit);
252                if let Some(meta) = script_meta {
253                    if let Some(output) = self.build_script_outputs.lock().unwrap().get(meta) {
254                        for cfg in &output.cfgs {
255                            args.push("--cfg".into());
256                            args.push(cfg.into());
257                        }
258
259                        for check_cfg in &output.check_cfgs {
260                            args.push("--check-cfg".into());
261                            args.push(check_cfg.into());
262                        }
263
264                        for (lt, arg) in &output.linker_args {
265                            if lt.applies_to(&unit.target) {
266                                args.push("-C".into());
267                                args.push(format!("link-arg={}", arg).into());
268                            }
269                        }
270                    }
271                }
272                args.extend(unit.rustdocflags.iter().map(Into::into));
273
274                use super::MessageFormat;
275                let format = match self.bcx.build_config.message_format {
276                    MessageFormat::Short => "short",
277                    MessageFormat::Human => "human",
278                    MessageFormat::Json { .. } => "json",
279                };
280                args.push("--error-format".into());
281                args.push(format.into());
282
283                self.compilation.to_doc_test.push(compilation::Doctest {
284                    unit: unit.clone(),
285                    args,
286                    unstable_opts,
287                    linker: self.compilation.target_linker(unit.kind).clone(),
288                    script_meta,
289                    env: artifact::get_env(&self, self.unit_deps(unit))?,
290                });
291            }
292
293            super::output_depinfo(&mut self, unit)?;
294        }
295
296        for (script_meta, output) in self.build_script_outputs.lock().unwrap().iter() {
297            self.compilation
298                .extra_env
299                .entry(*script_meta)
300                .or_insert_with(Vec::new)
301                .extend(output.env.iter().cloned());
302
303            for dir in output.library_paths.iter() {
304                self.compilation.native_dirs.insert(dir.clone());
305            }
306        }
307        Ok(self.compilation)
308    }
309
310    fn collect_tests_and_executables(&mut self, unit: &Unit) -> CargoResult<()> {
311        for output in self.outputs(unit)?.iter() {
312            if output.flavor == FileFlavor::DebugInfo || output.flavor == FileFlavor::Auxiliary {
313                continue;
314            }
315
316            let bindst = output.bin_dst();
317
318            if unit.mode == CompileMode::Test {
319                self.compilation
320                    .tests
321                    .push(self.unit_output(unit, &output.path));
322            } else if unit.target.is_executable() {
323                self.compilation
324                    .binaries
325                    .push(self.unit_output(unit, bindst));
326            } else if unit.target.is_cdylib()
327                && !self.compilation.cdylibs.iter().any(|uo| uo.unit == *unit)
328            {
329                self.compilation
330                    .cdylibs
331                    .push(self.unit_output(unit, bindst));
332            }
333        }
334        Ok(())
335    }
336
337    /// Returns the executable for the specified unit (if any).
338    pub fn get_executable(&mut self, unit: &Unit) -> CargoResult<Option<PathBuf>> {
339        let is_binary = unit.target.is_executable();
340        let is_test = unit.mode.is_any_test();
341        if !unit.mode.generates_executable() || !(is_binary || is_test) {
342            return Ok(None);
343        }
344        Ok(self
345            .outputs(unit)?
346            .iter()
347            .find(|o| o.flavor == FileFlavor::Normal)
348            .map(|output| output.bin_dst().clone()))
349    }
350
351    #[tracing::instrument(skip_all)]
352    pub fn prepare_units(&mut self) -> CargoResult<()> {
353        let dest = self.bcx.profiles.get_dir_name();
354        let host_layout = Layout::new(self.bcx.ws, None, &dest)?;
355        let mut targets = HashMap::new();
356        for kind in self.bcx.all_kinds.iter() {
357            if let CompileKind::Target(target) = *kind {
358                let layout = Layout::new(self.bcx.ws, Some(target), &dest)?;
359                targets.insert(target, layout);
360            }
361        }
362        self.primary_packages
363            .extend(self.bcx.roots.iter().map(|u| u.pkg.package_id()));
364        self.compilation
365            .root_crate_names
366            .extend(self.bcx.roots.iter().map(|u| u.target.crate_name()));
367
368        self.record_units_requiring_metadata();
369
370        let files = CompilationFiles::new(self, host_layout, targets);
371        self.files = Some(files);
372        Ok(())
373    }
374
375    /// Prepare this context, ensuring that all filesystem directories are in
376    /// place.
377    #[tracing::instrument(skip_all)]
378    pub fn prepare(&mut self) -> CargoResult<()> {
379        self.files
380            .as_mut()
381            .unwrap()
382            .host
383            .prepare()
384            .context("couldn't prepare build directories")?;
385        for target in self.files.as_mut().unwrap().target.values_mut() {
386            target
387                .prepare()
388                .context("couldn't prepare build directories")?;
389        }
390
391        let files = self.files.as_ref().unwrap();
392        for &kind in self.bcx.all_kinds.iter() {
393            let layout = files.layout(kind);
394            self.compilation
395                .root_output
396                .insert(kind, layout.dest().to_path_buf());
397            self.compilation
398                .deps_output
399                .insert(kind, layout.deps().to_path_buf());
400        }
401        Ok(())
402    }
403
404    pub fn files(&self) -> &CompilationFiles<'a, 'gctx> {
405        self.files.as_ref().unwrap()
406    }
407
408    /// Returns the filenames that the given unit will generate.
409    pub fn outputs(&self, unit: &Unit) -> CargoResult<Arc<Vec<OutputFile>>> {
410        self.files.as_ref().unwrap().outputs(unit, self.bcx)
411    }
412
413    /// Direct dependencies for the given unit.
414    pub fn unit_deps(&self, unit: &Unit) -> &[UnitDep] {
415        &self.bcx.unit_graph[unit]
416    }
417
418    /// Returns the `RunCustomBuild` Unit associated with the given Unit.
419    ///
420    /// If the package does not have a build script, this returns None.
421    pub fn find_build_script_unit(&self, unit: &Unit) -> Option<Unit> {
422        if unit.mode.is_run_custom_build() {
423            return Some(unit.clone());
424        }
425        self.bcx.unit_graph[unit]
426            .iter()
427            .find(|unit_dep| {
428                unit_dep.unit.mode.is_run_custom_build()
429                    && unit_dep.unit.pkg.package_id() == unit.pkg.package_id()
430            })
431            .map(|unit_dep| unit_dep.unit.clone())
432    }
433
434    /// Returns the metadata hash for the `RunCustomBuild` Unit associated with
435    /// the given unit.
436    ///
437    /// If the package does not have a build script, this returns None.
438    pub fn find_build_script_metadata(&self, unit: &Unit) -> Option<UnitHash> {
439        let script_unit = self.find_build_script_unit(unit)?;
440        Some(self.get_run_build_script_metadata(&script_unit))
441    }
442
443    /// Returns the metadata hash for a `RunCustomBuild` unit.
444    pub fn get_run_build_script_metadata(&self, unit: &Unit) -> UnitHash {
445        assert!(unit.mode.is_run_custom_build());
446        self.files().metadata(unit).unit_id()
447    }
448
449    pub fn is_primary_package(&self, unit: &Unit) -> bool {
450        self.primary_packages.contains(&unit.pkg.package_id())
451    }
452
453    /// Returns the list of filenames read by cargo to generate the [`BuildContext`]
454    /// (all `Cargo.toml`, etc.).
455    pub fn build_plan_inputs(&self) -> CargoResult<Vec<PathBuf>> {
456        // Keep sorted for consistency.
457        let mut inputs = BTreeSet::new();
458        // Note: dev-deps are skipped if they are not present in the unit graph.
459        for unit in self.bcx.unit_graph.keys() {
460            inputs.insert(unit.pkg.manifest_path().to_path_buf());
461        }
462        Ok(inputs.into_iter().collect())
463    }
464
465    /// Returns a [`UnitOutput`] which represents some information about the
466    /// output of a unit.
467    pub fn unit_output(&self, unit: &Unit, path: &Path) -> UnitOutput {
468        let script_meta = self.find_build_script_metadata(unit);
469        UnitOutput {
470            unit: unit.clone(),
471            path: path.to_path_buf(),
472            script_meta,
473        }
474    }
475
476    /// Check if any output file name collision happens.
477    /// See <https://github.com/rust-lang/cargo/issues/6313> for more.
478    #[tracing::instrument(skip_all)]
479    fn check_collisions(&self) -> CargoResult<()> {
480        let mut output_collisions = HashMap::new();
481        let describe_collision = |unit: &Unit, other_unit: &Unit, path: &PathBuf| -> String {
482            format!(
483                "The {} target `{}` in package `{}` has the same output \
484                     filename as the {} target `{}` in package `{}`.\n\
485                     Colliding filename is: {}\n",
486                unit.target.kind().description(),
487                unit.target.name(),
488                unit.pkg.package_id(),
489                other_unit.target.kind().description(),
490                other_unit.target.name(),
491                other_unit.pkg.package_id(),
492                path.display()
493            )
494        };
495        let suggestion =
496            "Consider changing their names to be unique or compiling them separately.\n\
497             This may become a hard error in the future; see \
498             <https://github.com/rust-lang/cargo/issues/6313>.";
499        let rustdoc_suggestion =
500            "This is a known bug where multiple crates with the same name use\n\
501             the same path; see <https://github.com/rust-lang/cargo/issues/6313>.";
502        let report_collision = |unit: &Unit,
503                                other_unit: &Unit,
504                                path: &PathBuf,
505                                suggestion: &str|
506         -> CargoResult<()> {
507            if unit.target.name() == other_unit.target.name() {
508                self.bcx.gctx.shell().warn(format!(
509                    "output filename collision.\n\
510                     {}\
511                     The targets should have unique names.\n\
512                     {}",
513                    describe_collision(unit, other_unit, path),
514                    suggestion
515                ))
516            } else {
517                self.bcx.gctx.shell().warn(format!(
518                    "output filename collision.\n\
519                    {}\
520                    The output filenames should be unique.\n\
521                    {}\n\
522                    If this looks unexpected, it may be a bug in Cargo. Please file a bug report at\n\
523                    https://github.com/rust-lang/cargo/issues/ with as much information as you\n\
524                    can provide.\n\
525                    cargo {} running on `{}` target `{}`\n\
526                    First unit: {:?}\n\
527                    Second unit: {:?}",
528                    describe_collision(unit, other_unit, path),
529                    suggestion,
530                    crate::version(),
531                    self.bcx.host_triple(),
532                    self.bcx.target_data.short_name(&unit.kind),
533                    unit,
534                    other_unit))
535            }
536        };
537
538        fn doc_collision_error(unit: &Unit, other_unit: &Unit) -> CargoResult<()> {
539            bail!(
540                "document output filename collision\n\
541                 The {} `{}` in package `{}` has the same name as the {} `{}` in package `{}`.\n\
542                 Only one may be documented at once since they output to the same path.\n\
543                 Consider documenting only one, renaming one, \
544                 or marking one with `doc = false` in Cargo.toml.",
545                unit.target.kind().description(),
546                unit.target.name(),
547                unit.pkg,
548                other_unit.target.kind().description(),
549                other_unit.target.name(),
550                other_unit.pkg,
551            );
552        }
553
554        let mut keys = self
555            .bcx
556            .unit_graph
557            .keys()
558            .filter(|unit| !unit.mode.is_run_custom_build())
559            .collect::<Vec<_>>();
560        // Sort for consistent error messages.
561        keys.sort_unstable();
562        // These are kept separate to retain compatibility with older
563        // versions, which generated an error when there was a duplicate lib
564        // or bin (but the old code did not check bin<->lib collisions). To
565        // retain backwards compatibility, this only generates an error for
566        // duplicate libs or duplicate bins (but not both). Ideally this
567        // shouldn't be here, but since there isn't a complete workaround,
568        // yet, this retains the old behavior.
569        let mut doc_libs = HashMap::new();
570        let mut doc_bins = HashMap::new();
571        for unit in keys {
572            if unit.mode.is_doc() && self.is_primary_package(unit) {
573                // These situations have been an error since before 1.0, so it
574                // is not a warning like the other situations.
575                if unit.target.is_lib() {
576                    if let Some(prev) = doc_libs.insert((unit.target.crate_name(), unit.kind), unit)
577                    {
578                        doc_collision_error(unit, prev)?;
579                    }
580                } else if let Some(prev) =
581                    doc_bins.insert((unit.target.crate_name(), unit.kind), unit)
582                {
583                    doc_collision_error(unit, prev)?;
584                }
585            }
586            for output in self.outputs(unit)?.iter() {
587                if let Some(other_unit) = output_collisions.insert(output.path.clone(), unit) {
588                    if unit.mode.is_doc() {
589                        // See https://github.com/rust-lang/rust/issues/56169
590                        // and https://github.com/rust-lang/rust/issues/61378
591                        report_collision(unit, other_unit, &output.path, rustdoc_suggestion)?;
592                    } else {
593                        report_collision(unit, other_unit, &output.path, suggestion)?;
594                    }
595                }
596                if let Some(hardlink) = output.hardlink.as_ref() {
597                    if let Some(other_unit) = output_collisions.insert(hardlink.clone(), unit) {
598                        report_collision(unit, other_unit, hardlink, suggestion)?;
599                    }
600                }
601                if let Some(ref export_path) = output.export_path {
602                    if let Some(other_unit) = output_collisions.insert(export_path.clone(), unit) {
603                        self.bcx.gctx.shell().warn(format!(
604                            "`--artifact-dir` filename collision.\n\
605                             {}\
606                             The exported filenames should be unique.\n\
607                             {}",
608                            describe_collision(unit, other_unit, export_path),
609                            suggestion
610                        ))?;
611                    }
612                }
613            }
614        }
615        Ok(())
616    }
617
618    /// Records the list of units which are required to emit metadata.
619    ///
620    /// Units which depend only on the metadata of others requires the others to
621    /// actually produce metadata, so we'll record that here.
622    fn record_units_requiring_metadata(&mut self) {
623        for (key, deps) in self.bcx.unit_graph.iter() {
624            for dep in deps {
625                if self.only_requires_rmeta(key, &dep.unit) {
626                    self.rmeta_required.insert(dep.unit.clone());
627                }
628            }
629        }
630    }
631
632    /// Returns whether when `parent` depends on `dep` if it only requires the
633    /// metadata file from `dep`.
634    pub fn only_requires_rmeta(&self, parent: &Unit, dep: &Unit) -> bool {
635        // We're only a candidate for requiring an `rmeta` file if we
636        // ourselves are building an rlib,
637        !parent.requires_upstream_objects()
638            && parent.mode == CompileMode::Build
639            // Our dependency must also be built as an rlib, otherwise the
640            // object code must be useful in some fashion
641            && !dep.requires_upstream_objects()
642            && dep.mode == CompileMode::Build
643    }
644
645    /// Returns whether when `unit` is built whether it should emit metadata as
646    /// well because some compilations rely on that.
647    pub fn rmeta_required(&self, unit: &Unit) -> bool {
648        self.rmeta_required.contains(unit)
649    }
650
651    /// Finds metadata for Doc/Docscrape units.
652    ///
653    /// rustdoc needs a -Cmetadata flag in order to recognize StableCrateIds that refer to
654    /// items in the crate being documented. The -Cmetadata flag used by reverse-dependencies
655    /// will be the metadata of the Cargo unit that generated the current library's rmeta file,
656    /// which should be a Check unit.
657    ///
658    /// If the current crate has reverse-dependencies, such a Check unit should exist, and so
659    /// we use that crate's metadata. If not, we use the crate's Doc unit so at least examples
660    /// scraped from the current crate can be used when documenting the current crate.
661    #[tracing::instrument(skip_all)]
662    pub fn compute_metadata_for_doc_units(&mut self) {
663        for unit in self.bcx.unit_graph.keys() {
664            if !unit.mode.is_doc() && !unit.mode.is_doc_scrape() {
665                continue;
666            }
667
668            let matching_units = self
669                .bcx
670                .unit_graph
671                .keys()
672                .filter(|other| {
673                    unit.pkg == other.pkg
674                        && unit.target == other.target
675                        && !other.mode.is_doc_scrape()
676                })
677                .collect::<Vec<_>>();
678            let metadata_unit = matching_units
679                .iter()
680                .find(|other| other.mode.is_check())
681                .or_else(|| matching_units.iter().find(|other| other.mode.is_doc()))
682                .unwrap_or(&unit);
683            self.metadata_for_doc_units
684                .insert(unit.clone(), self.files().metadata(metadata_unit));
685        }
686    }
687}
cargo/core/compiler/build_runner/mod.rs

cargo/core/compiler/build_runner/
mod.rs
