Skip to content

Commit d86d3bf

Browse files
committed
doc(build_context): module level doc
1 parent fa50fc1 commit d86d3bf

File tree

1 file changed

+51
-3
lines changed
  • src/cargo/core/compiler/build_context

1 file changed

+51
-3
lines changed

src/cargo/core/compiler/build_context/mod.rs

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
//! [`BuildContext`] is a (mostly) static information about a build task.
2+
13
use crate::core::compiler::unit_graph::UnitGraph;
24
use crate::core::compiler::{BuildConfig, CompileKind, Unit};
35
use crate::core::profiles::Profiles;
@@ -15,19 +17,42 @@ pub use self::target_info::{
1517
FileFlavor, FileType, RustDocFingerprint, RustcTargetData, TargetInfo,
1618
};
1719

18-
/// The build context, containing all information about a build task.
20+
/// The build context, containing complete infomration needed for a build task
21+
/// before it gets started.
1922
///
2023
/// It is intended that this is mostly static information. Stuff that mutates
21-
/// during the build can be found in the parent `Context`. (I say mostly,
24+
/// during the build can be found in the parent [`Context`]. (I say mostly,
2225
/// because this has internal caching, but nothing that should be observable
2326
/// or require &mut.)
27+
///
28+
/// As a result, almost every field on `BuildContext` is public, including
29+
///
30+
/// * a resolved [`UnitGraph`] of your dependencies,
31+
/// * a [`Profiles`] containing compiler flags presets,
32+
/// * a [`RustcTargetData`] containing host and target platform information,
33+
/// * and a [`PackageSet`] for further package downloads,
34+
///
35+
/// just to name a few. Learn more on each own documentation.
36+
///
37+
/// # How to use
38+
///
39+
/// To prepare a build task, you may not want to use [`BuildContext::new`] directly,
40+
/// since it is often too lower-level.
41+
/// Instead, [`ops::create_bcx`] is usually what you are looking for.
42+
///
43+
/// [`Context`]: crate::core::compiler::Context
44+
/// [`ops::create_bcx`]: crate::ops::create_bcx
2445
pub struct BuildContext<'a, 'cfg> {
2546
/// The workspace the build is for.
2647
pub ws: &'a Workspace<'cfg>,
2748

2849
/// The cargo configuration.
2950
pub config: &'cfg Config,
51+
52+
/// This contains a collection of compiler flags presets.
3053
pub profiles: Profiles,
54+
55+
/// Configuration information for a rustc build.
3156
pub build_config: &'a BuildConfig,
3257

3358
/// Extra compiler args for either `rustc` or `rustdoc`.
@@ -47,7 +72,7 @@ pub struct BuildContext<'a, 'cfg> {
4772
/// The dependency graph of units to compile.
4873
pub unit_graph: UnitGraph,
4974

50-
/// Reverse-dependencies of documented units, used by the rustdoc --scrape-examples flag.
75+
/// Reverse-dependencies of documented units, used by the `rustdoc --scrape-examples` flag.
5176
pub scrape_units: Vec<Unit>,
5277

5378
/// The list of all kinds that are involved in this build
@@ -88,6 +113,7 @@ impl<'a, 'cfg> BuildContext<'a, 'cfg> {
88113
})
89114
}
90115

116+
/// Information of the `rustc` this build task will use.
91117
pub fn rustc(&self) -> &Rustc {
92118
&self.target_data.rustc
93119
}
@@ -116,14 +142,36 @@ impl<'a, 'cfg> BuildContext<'a, 'cfg> {
116142
self.build_config.jobs
117143
}
118144

145+
/// Extra compiler flags to pass to `rustc` for a given unit.
146+
///
147+
/// Although it depends on the caller, in the current Cargo implementation,
148+
/// these flags take precendence over those from [`BuildContext::extra_args_for`].
149+
///
150+
/// As of now, these flags come from environment variables and configurations.
151+
/// See [`TargetInfo.rustflags`] for more on how Cargo collects them.
152+
///
153+
/// [`TargetInfo.rustflags`]: TargetInfo::rustflags
119154
pub fn rustflags_args(&self, unit: &Unit) -> &[String] {
120155
&self.target_data.info(unit.kind).rustflags
121156
}
122157

158+
/// Extra compiler flags to pass to `rustdoc` for a given unit.
159+
///
160+
/// Although it depends on the caller, in the current Cargo implementation,
161+
/// these flags take precendence over those from [`BuildContext::extra_args_for`].
162+
///
163+
/// As of now, these flags come from environment variables and configurations.
164+
/// See [`TargetInfo.rustdocflags`] for more on how Cargo collects them.
165+
///
166+
/// [`TargetInfo.rustdocflags`]: TargetInfo::rustdocflags
123167
pub fn rustdocflags_args(&self, unit: &Unit) -> &[String] {
124168
&self.target_data.info(unit.kind).rustdocflags
125169
}
126170

171+
/// Extra compiler args for either `rustc` or `rustdoc`.
172+
///
173+
/// As of now, these flags come from the trailing args of either
174+
/// `cargo rustc` or `cargo rustdoc`.
127175
pub fn extra_args_for(&self, unit: &Unit) -> Option<&Vec<String>> {
128176
self.extra_compiler_args.get(unit)
129177
}

0 commit comments

Comments
 (0)