Struct cargo::core::compiler::BuildContext

pub struct BuildContext<'a, 'cfg> {
    pub ws: &'a Workspace<'cfg>,
    pub config: &'cfg Config,
    pub profiles: Profiles,
    pub build_config: &'a BuildConfig,
    pub extra_compiler_args: HashMap<Unit, Vec<String>>,
    pub packages: PackageSet<'cfg>,
    pub target_data: RustcTargetData<'cfg>,
    pub roots: Vec<Unit>,
    pub unit_graph: UnitGraph,
    pub scrape_units: Vec<Unit>,
    pub all_kinds: HashSet<CompileKind>,
}

The build context, containing complete information needed for a build task before it gets started.

It is intended that this is mostly static information. Stuff that mutates during the build can be found in the parent Context. (I say mostly, because this has internal caching, but nothing that should be observable or require &mut.)

As a result, almost every field on BuildContext is public, including

• a resolved UnitGraph of your dependencies,
• a Profiles containing compiler flags presets,
• a RustcTargetData containing host and target platform information,
• and a PackageSet for further package downloads,

just to name a few. Learn more on each own documentation.

How to use

To prepare a build task, you may not want to use BuildContext::new directly, since it is often too lower-level. Instead, ops::create_bcx is usually what you are looking for.

After a BuildContext is built, the next stage of building is handled in Context.

Fields

ws: &'a Workspace<'cfg>

The workspace the build is for.

config: &'cfg Config

The cargo configuration.

profiles: Profiles

This contains a collection of compiler flags presets.

build_config: &'a BuildConfig

Configuration information for a rustc build.

extra_compiler_args: HashMap<Unit, Vec<String>>

Extra compiler args for either rustc or rustdoc.

packages: PackageSet<'cfg>

Package downloader.

This holds ownership of the Package objects.

target_data: RustcTargetData<'cfg>

Information about rustc and the target platform.

roots: Vec<Unit>

The root units of unit_graph (units requested on the command-line).

unit_graph: UnitGraph

The dependency graph of units to compile.

scrape_units: Vec<Unit>

Reverse-dependencies of documented units, used by the rustdoc --scrape-examples flag.

all_kinds: HashSet<CompileKind>

The list of all kinds that are involved in this build

Implementations

impl<'a, 'cfg> BuildContext<'a, 'cfg>

pub fn new( ws: &'a Workspace<'cfg>, packages: PackageSet<'cfg>, build_config: &'a BuildConfig, profiles: Profiles, extra_compiler_args: HashMap<Unit, Vec<String>>, target_data: RustcTargetData<'cfg>, roots: Vec<Unit>, unit_graph: UnitGraph, scrape_units: Vec<Unit> ) -> CargoResult<BuildContext<'a, 'cfg>>

pub fn rustc(&self) -> &Rustc

Information of the rustc this build task will use.

pub fn linker(&self, kind: CompileKind) -> Option<PathBuf>

Gets the user-specified linker for a particular host or target.

pub fn host_triple(&self) -> InternedString

Gets the host architecture triple.

For example, x86_64-unknown-linux-gnu, would be

• machine: x86_64,
• hardware-platform: unknown,
• operating system: linux-gnu.

pub fn jobs(&self) -> u32

Gets the number of jobs specified for this build.

pub fn rustflags_args(&self, unit: &Unit) -> &[String]

Extra compiler flags to pass to rustc for a given unit.

Although it depends on the caller, in the current Cargo implementation, these flags take precedence over those from BuildContext::extra_args_for.

As of now, these flags come from environment variables and configurations. See TargetInfo.rustflags for more on how Cargo collects them.

pub fn rustdocflags_args(&self, unit: &Unit) -> &[String]

Extra compiler flags to pass to rustdoc for a given unit.

Although it depends on the caller, in the current Cargo implementation, these flags take precedence over those from BuildContext::extra_args_for.

As of now, these flags come from environment variables and configurations. See TargetInfo.rustdocflags for more on how Cargo collects them.

pub fn extra_args_for(&self, unit: &Unit) -> Option<&Vec<String>>

Extra compiler args for either rustc or rustdoc.

As of now, these flags come from the trailing args of either cargo rustc or cargo rustdoc.

impl BuildContext<'_, '_>

pub fn scrape_units_have_dep_on<'a>(&'a self, unit: &'a Unit) -> Vec<&'a Unit>

Returns the set of Docscrape units that have a direct dependency on unit.

RunCustomBuild units are excluded because we allow failures from type checks but not build script executions. A plain old cargo doc would just die if a build script execution fails, there is no reason for -Zrustdoc-scrape-examples to keep going.

pub fn unit_can_fail_for_docscraping(&self, unit: &Unit) -> bool

Returns true if this unit is needed for doing doc-scraping and is also allowed to fail without killing the build.