cargo/core/compiler/build_context/
mod.rs

1//! [`BuildContext`] is a (mostly) static information about a build task.
2
3use crate::core::PackageSet;
4use crate::core::Workspace;
5use crate::core::compiler::BuildConfig;
6use crate::core::compiler::CompileKind;
7use crate::core::compiler::Unit;
8use crate::core::compiler::UnitIndex;
9use crate::core::compiler::unit_graph::UnitGraph;
10use crate::core::profiles::Profiles;
11use crate::util::Rustc;
12use crate::util::context::GlobalContext;
13use crate::util::errors::CargoResult;
14use crate::util::interning::InternedString;
15use crate::util::logger::BuildLogger;
16use std::collections::{HashMap, HashSet};
17
18mod target_info;
19pub use self::target_info::FileFlavor;
20pub use self::target_info::FileType;
21pub use self::target_info::RustcTargetData;
22pub use self::target_info::TargetInfo;
23
24/// The build context, containing complete information needed for a build task
25/// before it gets started.
26///
27/// It is intended that this is mostly static information. Stuff that mutates
28/// during the build can be found in the parent [`BuildRunner`]. (I say mostly,
29/// because this has internal caching, but nothing that should be observable
30/// or require &mut.)
31///
32/// As a result, almost every field on `BuildContext` is public, including
33///
34/// * a resolved [`UnitGraph`] of your dependencies,
35/// * a [`Profiles`] containing compiler flags presets,
36/// * a [`RustcTargetData`] containing host and target platform information,
37/// * and a [`PackageSet`] for further package downloads,
38///
39/// just to name a few. Learn more on each own documentation.
40///
41/// # How to use
42///
43/// To prepare a build task, you may not want to use [`BuildContext::new`] directly,
44/// since it is often too lower-level.
45/// Instead, [`ops::create_bcx`] is usually what you are looking for.
46///
47/// After a `BuildContext` is built, the next stage of building is handled in [`BuildRunner`].
48///
49/// [`BuildRunner`]: crate::core::compiler::BuildRunner
50/// [`ops::create_bcx`]: crate::ops::create_bcx
51pub struct BuildContext<'a, 'gctx> {
52    /// The workspace the build is for.
53    pub ws: &'a Workspace<'gctx>,
54
55    /// The cargo context.
56    pub gctx: &'gctx GlobalContext,
57
58    /// Build logger for `-Zbuild-analysis`.
59    pub logger: Option<&'a BuildLogger>,
60
61    /// This contains a collection of compiler flags presets.
62    pub profiles: Profiles,
63
64    /// Configuration information for a rustc build.
65    pub build_config: &'a BuildConfig,
66
67    /// Extra compiler args for either `rustc` or `rustdoc`.
68    pub extra_compiler_args: HashMap<Unit, Vec<String>>,
69
70    /// Package downloader.
71    ///
72    /// This holds ownership of the `Package` objects.
73    pub packages: PackageSet<'gctx>,
74
75    /// Information about rustc and the target platform.
76    pub target_data: RustcTargetData<'gctx>,
77
78    /// The root units of `unit_graph` (units requested on the command-line).
79    pub roots: Vec<Unit>,
80
81    /// The dependency graph of units to compile.
82    pub unit_graph: UnitGraph,
83
84    /// A map from unit to index.
85    pub unit_to_index: HashMap<Unit, UnitIndex>,
86
87    /// Reverse-dependencies of documented units, used by the `rustdoc --scrape-examples` flag.
88    pub scrape_units: Vec<Unit>,
89
90    /// The list of all kinds that are involved in this build
91    pub all_kinds: HashSet<CompileKind>,
92}
93
94impl<'a, 'gctx> BuildContext<'a, 'gctx> {
95    pub fn new(
96        ws: &'a Workspace<'gctx>,
97        logger: Option<&'a BuildLogger>,
98        packages: PackageSet<'gctx>,
99        build_config: &'a BuildConfig,
100        profiles: Profiles,
101        extra_compiler_args: HashMap<Unit, Vec<String>>,
102        target_data: RustcTargetData<'gctx>,
103        roots: Vec<Unit>,
104        unit_graph: UnitGraph,
105        unit_to_index: HashMap<Unit, UnitIndex>,
106        scrape_units: Vec<Unit>,
107    ) -> CargoResult<BuildContext<'a, 'gctx>> {
108        let all_kinds = unit_graph
109            .keys()
110            .map(|u| u.kind)
111            .chain(build_config.requested_kinds.iter().copied())
112            .chain(std::iter::once(CompileKind::Host))
113            .collect();
114
115        Ok(BuildContext {
116            ws,
117            gctx: ws.gctx(),
118            logger,
119            packages,
120            build_config,
121            profiles,
122            extra_compiler_args,
123            target_data,
124            roots,
125            unit_graph,
126            unit_to_index,
127            scrape_units,
128            all_kinds,
129        })
130    }
131
132    /// Information of the `rustc` this build task will use.
133    pub fn rustc(&self) -> &Rustc {
134        &self.target_data.rustc
135    }
136
137    /// Gets the host architecture triple.
138    ///
139    /// For example, `x86_64-unknown-linux-gnu`, would be
140    /// - machine: `x86_64`,
141    /// - hardware-platform: `unknown`,
142    /// - operating system: `linux-gnu`.
143    pub fn host_triple(&self) -> InternedString {
144        self.target_data.rustc.host
145    }
146
147    /// Gets the number of jobs specified for this build.
148    pub fn jobs(&self) -> u32 {
149        self.build_config.jobs
150    }
151
152    /// Extra compiler args for either `rustc` or `rustdoc`.
153    ///
154    /// As of now, these flags come from the trailing args of either
155    /// `cargo rustc` or `cargo rustdoc`.
156    pub fn extra_args_for(&self, unit: &Unit) -> Option<&Vec<String>> {
157        self.extra_compiler_args.get(unit)
158    }
159}
cargo/core/compiler/build_context/mod.rs

cargo/core/compiler/build_context/
mod.rs
