Struct ConditionalLink 

pub struct ConditionalLink<'g> { /* private fields */ }

A feature dependency that is conditionally activated.

A ConditionalLink is typically a link across packages. For example:

[package]
name = "main"

[dependencies]
dep = { ... }

[dev-dependencies]
dev-dep = { ... }

[target.'cfg(unix)'.dependencies]
unix-dep = { ... }

[features]
feat = ["dep/feat", "dev-dep/feat", "unix-dep/feat"]

In this example, there are ConditionalLinks from main/feat to dep/feat, dev-dep/feat and unix-dep/feat. Each link is only activated if the conditions for it are met. For example, the link to dev-dep/feat is only followed if Cargo is interested in dev-dependencies of main.

If a dependency, for example unix-dep above, is optional, an implicit feature is created in the package main with the name unix-dep. In this case, the dependency from main/feat to main/unix-dep is also a ConditionalLink representing the same cfg(unix) condition.

Implementations

impl<'g> ConditionalLink<'g>

pub fn from(&self) -> FeatureMetadata<'g>

Returns the feature which depends on the to feature.

pub fn to(&self) -> FeatureMetadata<'g>

Returns the feature which is depended on by the from feature.

pub fn endpoints(&self) -> (FeatureMetadata<'g>, FeatureMetadata<'g>)

Returns the endpoints as a pair of features (from, to).

pub fn normal(&self) -> PlatformStatus<'g>

Returns details about this feature dependency from the [dependencies] section.

pub fn build(&self) -> PlatformStatus<'g>

Returns details about this feature dependency from the [build-dependencies] section.

pub fn dev(&self) -> PlatformStatus<'g>

Returns details about this feature dependency from the [dev-dependencies] section.

pub fn status_for_kind(&self, kind: DependencyKind) -> PlatformStatus<'g>

Returns details about this feature dependency from the section specified by the given dependency kind.

pub fn dev_only(&self) -> bool

Returns true if this edge is dev-only, i.e. code from this edge will not be included in normal builds.

This is scoped to the declarations for this link. For example, a dependency might be optional as a normal dependency but required as a dev-dependency. In that case, the Required version of the link is dev-only while the Optional half is not. Unsplit is the union of both, so it isn’t dev-only either.

pub fn declarations(&self) -> LinkDeclarations

Returns the declarations of the dependency that this link’s platform statuses were derived from.

A package can declare the same dependency more than once, and some of those declarations can be optional while others are required. For example:

[dependencies]
foo = { version = "1" }

[build-dependencies]
foo = { version = "1", optional = true }

[features]
weak = ["foo?/std"]

Cargo applies foo?/std to each declaration separately.

• The required normal dependency gets std as soon as weak is enabled.
• The optional build dependency gets std only if dep:foo is also activated.

To model this, FeatureQuery::resolve_with may call the visitor twice for the link from main/weak to foo/std:

• Once with a Required link. Here, normal is always enabled and build is never enabled.
• Once with an Optional link. Here, normal is never enabled and build is always enabled.

Both links have the same from and to; this method is the way to tell them apart. The link is followed if the visitor accepts either one.

If foo has no required declarations for this package, the required link is skipped. When each link is offered depends on the query’s direction; see FeatureLinkVisitor::visit_link.

Outside of a resolve, the same edge is a single link. FeatureSet::conditional_links returns it once, with Unsplit and the union of both sets of statuses.

For other kinds of links, the return value is fixed:

• A link from a feature with foo/std to foo’s std feature is Unsplit, since foo/std applies to every declaration of foo that resolves to that package.
• A link from a feature with foo/std to dep:foo, or to a feature named foo in the same package, is Optional, since only optional declarations of foo activate these.
• A link from a feature with dep:foo to dep:foo is Unsplit, since dep:foo activates every declaration of foo.
• A link from a package’s base feature into a dependency is Required.
• A link from dep:foo into foo is Optional.

pub fn package_links( &self, ) -> impl ExactSizeIterator<Item = PackageLink<'g>> + 'g

Returns the PackageLinks this ConditionalLink was derived from.

This is usually one link, but in some circumstances a single name can resolve to several packages. For example, consider this Cargo.toml:

[package]
name = "main"

[dependencies]
serde = { package = "serde_core", version = "1", optional = true }

# Never enabled on any platform, but still resolved and locked.
[target.'cfg(any())'.dependencies]
serde = { version = "1", optional = true }

[features]
serde = ["dep:serde", "serde/std"]

The package graph has two links out of main, main -> serde_core and main -> serde, both with the dependency name serde. The feature serde produces three conditional links:

• main/serde -> main/dep:serde, from dep:serde. This activates the dependency name, so this method returns both main -> serde_core and main -> serde. The link’s platform status is the union of theirs.
• main/serde -> serde_core/std, from serde/std. This method returns only main -> serde_core.
• main/serde -> serde/std, also from serde/std. This method returns only main -> serde.

A link that covers only some declarations (see declarations) omits packages with none of those declarations. For example, a link from foo/std to dep:foo covers only optional declarations, so it omits a package that is only ever a required dependency named foo.

The order in which links are returned is unspecified.

Trait Implementations

impl<'g> Clone for ConditionalLink<'g>

fn clone(&self) -> ConditionalLink<'g>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'g> Copy for ConditionalLink<'g>

impl Debug for ConditionalLink<'_>

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

Formats the value using the given formatter.