Struct guppy::graph::PackageGraph

pub struct PackageGraph { /* private fields */ }

A graph of packages and dependencies between them, parsed from metadata returned by cargo metadata.

For examples on how to use PackageGraph, see the examples directory in this crate.

Implementations

impl PackageGraph

pub fn feature_graph(&self) -> FeatureGraph<'_>

Returns a derived graph representing every feature of every package.

The feature graph is constructed the first time this method is called. The graph is cached so that repeated calls to this method are cheap.

impl PackageGraph

pub fn from_command(command: &mut MetadataCommand) -> Result<Self, Error>

Executes the given MetadataCommand and constructs a PackageGraph from it.

pub fn from_metadata(metadata: CargoMetadata) -> Result<Self, Error>

Parses the given Metadata and constructs a PackageGraph from it.

pub fn from_json(json: impl AsRef<str>) -> Result<Self, Error>

Constructs a package graph from the given JSON output of cargo metadata.

Generally, guppy expects the cargo metadata command to be run with --all-features, so that guppy has a full view of the dependency graph.

For full functionality, cargo metadata should be run without --no-deps, so that guppy knows about third-party crates and dependency edges. However, guppy supports a “light” mode if --no-deps is run, in which case the following limitations will apply:

• dependency queries will not work
• there will be no information about non-workspace crates

pub fn workspace(&self) -> Workspace<'_>

Returns information about the workspace.

pub fn package_ids(
    &self
) -> impl Iterator<Item = &PackageId> + ExactSizeIterator

Returns an iterator over all the package IDs in this graph.

pub fn packages(
    &self
) -> impl Iterator<Item = PackageMetadata<'_>> + ExactSizeIterator

Returns an iterator over all the packages in this graph.

pub fn metadata(
    &self,
    package_id: &PackageId
) -> Result<PackageMetadata<'_>, Error>

Returns the metadata for the given package ID.

pub fn package_count(&self) -> usize

Returns the number of packages in this graph.

pub fn link_count(&self) -> usize

Returns the number of links in this graph.

pub fn new_depends_cache(&self) -> DependsCache<'_>

Creates a new cache for depends_on queries.

The cache is optional but can speed up some queries.

pub fn depends_on(
    &self,
    package_a: &PackageId,
    package_b: &PackageId
) -> Result<bool, Error>

Returns true if package_a depends (directly or indirectly) on package_b.

In other words, this returns true if package_b is a (possibly transitive) dependency of package_a.

This also returns true if package_a is the same as package_b.

For repeated queries, consider using new_depends_cache to speed up queries.

pub fn directly_depends_on(
    &self,
    package_a: &PackageId,
    package_b: &PackageId
) -> Result<bool, Error>

Returns true if package_a directly depends on package_b.

In other words, this returns true if package_b is a direct dependency of package_a.

This returns false if package_a is the same as package_b.

pub fn cycles(&self) -> Cycles<'_>

Returns information about dependency cycles in this graph.

For more information, see the documentation for Cycles.

impl PackageGraph

Helpers for property testing

The methods in this section allow a PackageGraph to be used in property-based testing scenarios.

Currently, proptest 1 is supported if the proptest1 feature is enabled.

pub fn prop010_id_strategy(&self) -> impl Strategy<Value = &PackageId>

This is supported on crate feature proptest1 only.

Returns a Strategy that generates random package IDs from this graph.

Requires the proptest1 feature to be enabled.

Panics

Panics if there are no packages in this PackageGraph.

pub fn prop010_link_strategy(&self) -> impl Strategy<Value = PackageLink<'_>>

This is supported on crate feature proptest1 only.

Returns a Strategy that generates random dependency links from this graph.

Requires the proptest1 feature to be enabled.

Panics

Panics if there are no dependency edges in this PackageGraph.

pub fn prop010_resolver_strategy(
    &self
) -> impl Strategy<Value = Prop010Resolver>

This is supported on crate feature proptest1 only.

Returns a Strategy that generates a random PackageResolver instance from this graph.

Requires the proptest1 feature to be enabled.

pub fn prop010_cargo_options_strategy(
    &self
) -> impl Strategy<Value = CargoOptions<'_>>

This is supported on crate feature proptest1 only.

Returns a Strategy that generates a random CargoOptions from this graph.

Requires the proptest1 feature to be enabled.

impl PackageGraph

Queries

The methods in this section create queries over subsets of this package graph. Use the methods here to analyze transitive dependencies.

pub fn query_workspace(&self) -> PackageQuery<'_>

Creates a new forward query over the entire workspace.

query_workspace will select all workspace packages and their transitive dependencies. To create a PackageSet with just workspace packages, use resolve_workspace.

pub fn query_workspace_paths(
    &self,
    paths: impl IntoIterator<Item = impl AsRef<Utf8Path>>
) -> Result<PackageQuery<'_>, Error>

Creates a new forward query over the specified workspace packages by path.

Returns an error if any workspace paths were unknown.

pub fn query_workspace_names(
    &self,
    names: impl IntoIterator<Item = impl AsRef<str>>
) -> Result<PackageQuery<'_>, Error>

Creates a new forward query over the specified workspace packages by name.

This is similar to cargo’s --package option.

Returns an error if any package names were unknown.

pub fn query_directed<'g, 'a>(
    &'g self,
    package_ids: impl IntoIterator<Item = &'a PackageId>,
    dep_direction: DependencyDirection
) -> Result<PackageQuery<'g>, Error>

Creates a new query that returns transitive dependencies of the given packages in the specified direction.

Returns an error if any package IDs are unknown.

pub fn query_forward<'g, 'a>(
    &'g self,
    package_ids: impl IntoIterator<Item = &'a PackageId>
) -> Result<PackageQuery<'g>, Error>

Creates a new query that returns transitive dependencies of the given packages.

Returns an error if any package IDs are unknown.

pub fn query_reverse<'g, 'a>(
    &'g self,
    package_ids: impl IntoIterator<Item = &'a PackageId>
) -> Result<PackageQuery<'g>, Error>

Creates a new query that returns transitive reverse dependencies of the given packages.

Returns an error if any package IDs are unknown.

impl PackageGraph

pub fn resolve_all(&self) -> PackageSet<'_>

Creates a new PackageSet consisting of all members of this package graph.

This is normally the same as query_workspace().resolve(), but can differ if packages have been replaced with [patch] or [replace].

In most situations, query_workspace is preferred. Use resolve_all if you know you need parts of the graph that aren’t accessible from the workspace.

pub fn resolve_none(&self) -> PackageSet<'_>

Creates a new, empty PackageSet associated with this package graph.

pub fn resolve_ids<'a>(
    &self,
    package_ids: impl IntoIterator<Item = &'a PackageId>
) -> Result<PackageSet<'_>, Error>

Creates a new PackageSet consisting of the specified package IDs.

This does not include transitive dependencies. To do so, use the query_ methods.

Returns an error if any package IDs are unknown.

pub fn resolve_workspace(&self) -> PackageSet<'_>

Creates a new PackageSet consisting of all packages in this workspace.

This does not include transitive dependencies. To do so, use query_workspace.

pub fn resolve_workspace_paths(
    &self,
    paths: impl IntoIterator<Item = impl AsRef<Utf8Path>>
) -> Result<PackageSet<'_>, Error>

Creates a new PackageSet consisting of the specified workspace packages by path.

This does not include transitive dependencies. To do so, use query_workspace_paths.

Returns an error if any workspace paths are unknown.

pub fn resolve_workspace_names(
    &self,
    names: impl IntoIterator<Item = impl AsRef<str>>
) -> Result<PackageSet<'_>, Error>

Creates a new PackageSet consisting of the specified workspace packages by name.

This does not include transitive dependencies. To do so, use query_workspace_names.

Returns an error if any workspace names are unknown.

pub fn resolve_package_name(&self, name: impl AsRef<str>) -> PackageSet<'_>

Creates a new PackageSet consisting of packages with the given name.

The result is empty if there are no packages with the given name.

impl PackageGraph

pub fn metadata_by_summary_id(
    &self,
    summary_id: &SummaryId
) -> Result<PackageMetadata<'_>, Error>

This is supported on crate feature summaries only.

Converts this SummaryId to a PackageMetadata.

Returns an error if the summary ID could not be matched.

Requires the summaries feature to be enabled.

Trait Implementations

impl Clone for PackageGraph

fn clone(&self) -> PackageGraph

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for PackageGraph

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

Formats the value using the given formatter.

impl<'a> TryFrom<&'a MetadataCommand> for PackageGraph

type Error = Error

The type returned in the event of a conversion error.

fn try_from(command: &'a MetadataCommand) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<CargoMetadata> for PackageGraph

type Error = Error

The type returned in the event of a conversion error.

fn try_from(metadata: CargoMetadata) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<MetadataCommand> for PackageGraph

Although consuming a MetadataCommand is not required for building a PackageGraph, this impl is provided for convenience.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(command: MetadataCommand) -> Result<Self, Self::Error>

Performs the conversion.