1
+ //! [`BuildContext`] is a (mostly) static information about a build task.
2
+
1
3
use crate :: core:: compiler:: unit_graph:: UnitGraph ;
2
4
use crate :: core:: compiler:: { BuildConfig , CompileKind , Unit } ;
3
5
use crate :: core:: profiles:: Profiles ;
@@ -15,19 +17,42 @@ pub use self::target_info::{
15
17
FileFlavor , FileType , RustDocFingerprint , RustcTargetData , TargetInfo ,
16
18
} ;
17
19
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.
19
22
///
20
23
/// 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,
22
25
/// because this has internal caching, but nothing that should be observable
23
26
/// 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
24
45
pub struct BuildContext < ' a , ' cfg > {
25
46
/// The workspace the build is for.
26
47
pub ws : & ' a Workspace < ' cfg > ,
27
48
28
49
/// The cargo configuration.
29
50
pub config : & ' cfg Config ,
51
+
52
+ /// This contains a collection of compiler flags presets.
30
53
pub profiles : Profiles ,
54
+
55
+ /// Configuration information for a rustc build.
31
56
pub build_config : & ' a BuildConfig ,
32
57
33
58
/// Extra compiler args for either `rustc` or `rustdoc`.
@@ -47,7 +72,7 @@ pub struct BuildContext<'a, 'cfg> {
47
72
/// The dependency graph of units to compile.
48
73
pub unit_graph : UnitGraph ,
49
74
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.
51
76
pub scrape_units : Vec < Unit > ,
52
77
53
78
/// The list of all kinds that are involved in this build
@@ -88,6 +113,7 @@ impl<'a, 'cfg> BuildContext<'a, 'cfg> {
88
113
} )
89
114
}
90
115
116
+ /// Information of the `rustc` this build task will use.
91
117
pub fn rustc ( & self ) -> & Rustc {
92
118
& self . target_data . rustc
93
119
}
@@ -116,14 +142,36 @@ impl<'a, 'cfg> BuildContext<'a, 'cfg> {
116
142
self . build_config . jobs
117
143
}
118
144
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
119
154
pub fn rustflags_args ( & self , unit : & Unit ) -> & [ String ] {
120
155
& self . target_data . info ( unit. kind ) . rustflags
121
156
}
122
157
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
123
167
pub fn rustdocflags_args ( & self , unit : & Unit ) -> & [ String ] {
124
168
& self . target_data . info ( unit. kind ) . rustdocflags
125
169
}
126
170
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`.
127
175
pub fn extra_args_for ( & self , unit : & Unit ) -> Option < & Vec < String > > {
128
176
self . extra_compiler_args . get ( unit)
129
177
}
0 commit comments