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