Struct cargo::core::profiles::UnitFor

pub struct UnitFor {
    host: bool,
    host_features: bool,
    panic_setting: PanicSetting,
    root_compile_kind: CompileKind,
    artifact_target_for_features: Option<CompileTarget>,
}

Flags used in creating Units to indicate the purpose for the target, and to ensure the target’s dependencies have the correct settings.

This means these are passed down from the root of the dependency tree to apply to most child dependencies.

Fields

host: bool

A target for build.rs or any of its dependencies, or a proc-macro or any of its dependencies. This enables build-override profiles for these targets.

An invariant is that if host_features is true, host must be true.

Note that this is true for RunCustomBuild units, even though that unit should not use build-override profiles. This is a bit of a special case. When computing the RunCustomBuild unit, it manually uses the get_profile_run_custom_build method to get the correct profile information for the unit. host needs to be true so that all of the dependencies of that RunCustomBuild unit have this flag be sticky (and forced to true for all further dependencies) — which is the whole point of UnitFor.

host_features: bool

A target for a build dependency or proc-macro (or any of its dependencies). This is used for computing features of build dependencies and proc-macros independently of other dependency kinds.

The subtle difference between this and host is that the build script for a non-host package sets this to false because it wants the features of the non-host package (whereas host is true because the build script is being built for the host). host_features becomes true for build-dependencies or proc-macros, or any of their dependencies. For example, with this dependency tree:

foo
├── foo build.rs
│   └── shared_dep (BUILD dependency)
│       └── shared_dep build.rs
└── shared_dep (Normal dependency)
    └── shared_dep build.rs

In this example, foo build.rs is HOST=true, HOST_FEATURES=false. This is so that foo build.rs gets the profile settings for build scripts (HOST=true) and features of foo (HOST_FEATURES=false) because build scripts need to know which features their package is being built with.

But in the case of shared_dep, when built as a build dependency, both flags are true (it only wants the build-dependency features). When shared_dep is built as a normal dependency, then shared_dep build.rs is HOST=true, HOST_FEATURES=false for the same reasons that foo’s build script is set that way.

panic_setting: PanicSetting

How Cargo processes the panic setting or profiles.

root_compile_kind: CompileKind

The compile kind of the root unit for which artifact dependencies are built. This is required particularly for the target = "target" setting of artifact dependencies which mean to inherit the --target specified on the command-line. However, that is a multi-value argument and root units are already created to reflect one unit per –target. Thus we have to build one artifact with the correct target for each of these trees. Note that this will always be set as we don’t initially know if there are artifacts that make use of it.

artifact_target_for_features: Option<CompileTarget>

This is only set for artifact dependencies which have their <target-triple>|target set. If so, this information is used as part of the key for resolving their features, allowing for target-dependent feature resolution within the entire dependency tree. Note that this target corresponds to the target used to build the units in that dependency tree, too, but this copy of it is specifically used for feature lookup.

Implementations

impl UnitFor

pub fn new_normal(root_compile_kind: CompileKind) -> UnitFor

A unit for a normal target/dependency (i.e., not custom build, proc macro/plugin, or test/bench).

pub fn new_host(host_features: bool, root_compile_kind: CompileKind) -> UnitFor

A unit for a custom build script or proc-macro or its dependencies.

The host_features parameter is whether or not this is for a build dependency or proc-macro (something that requires being built “on the host”). Build scripts for non-host units should use false because they want to use the features of the package they are running for.

pub fn new_compiler(root_compile_kind: CompileKind) -> UnitFor

A unit for a compiler plugin or their dependencies.

pub fn new_test(config: &Config, root_compile_kind: CompileKind) -> UnitFor

A unit for a test/bench target or their dependencies.

Note that config is taken here for unstable CLI features to detect whether panic=abort is supported for tests. Historical versions of rustc did not support this, but newer versions do with an unstable compiler flag.

pub fn new_host_test(config: &Config, root_compile_kind: CompileKind) -> UnitFor

This is a special case for unit tests of a proc-macro.

Proc-macro unit tests are forced to be run on the host.

pub fn with_dependency( self, parent: &Unit, dep_target: &Target, root_compile_kind: CompileKind ) -> UnitFor

Returns a new copy updated based on the target dependency.

This is where the magic happens that the host/host_features settings transition in a sticky fashion. As the dependency graph is being built, once those flags are set, they stay set for the duration of that portion of tree.

pub fn for_custom_build(self) -> UnitFor

pub(crate) fn with_artifact_features(self, artifact: &Artifact) -> UnitFor

Set the artifact compile target for use in features using the given artifact.

pub(crate) fn with_artifact_features_from_resolved_compile_kind( self, kind: Option<CompileKind> ) -> UnitFor

Set the artifact compile target as determined by a resolved compile target. This is used if target = "target".

pub fn is_for_host(&self) -> bool

Returns true if this unit is for a build script or any of its dependencies, or a proc macro or any of its dependencies.

pub fn is_for_host_features(&self) -> bool

fn panic_setting(&self) -> PanicSetting

Returns how panic settings should be handled for this profile

pub(crate) fn map_to_features_for( &self, dep_artifact: Option<&Artifact> ) -> FeaturesFor

We might contain a parent artifact compile kind for features already, but will gladly accept the one of this dependency as an override as it defines how the artifact is built. If we are an artifact but don’t specify a target, we assume the default compile kind that is suitable in this situation.

pub(crate) fn root_compile_kind(&self) -> CompileKind

Trait Implementations

impl Clone for UnitFor

fn clone(&self) -> UnitFor

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnitFor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for UnitFor

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for UnitFor

fn cmp(&self, other: &UnitFor) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<UnitFor> for UnitFor

fn eq(&self, other: &UnitFor) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<UnitFor> for UnitFor

fn partial_cmp(&self, other: &UnitFor) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for UnitFor

impl Eq for UnitFor

impl StructuralEq for UnitFor

impl StructuralPartialEq for UnitFor

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 40 bytes