Struct guppy::graph::PackageGraph

source ·
pub struct PackageGraph { /* private fields */ }
Expand description

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§

source§

impl PackageGraph

source

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.

source§

impl PackageGraph

source

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

Executes the given MetadataCommand and constructs a PackageGraph from it.

source

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

Parses the given Metadata and constructs a PackageGraph from it.

source

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
source

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

Returns information about the workspace.

source

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

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

source

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

Returns an iterator over all the packages in this graph.

source

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

Returns the metadata for the given package ID.

source

pub fn package_count(&self) -> usize

Returns the number of packages in this graph.

Returns the number of links in this graph.

source

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.

source

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.

source

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.

source

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

Returns information about dependency cycles in this graph.

For more information, see the documentation for Cycles.

source§

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.

source

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

Available 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.

Available 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.

source

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

Available on crate feature proptest1 only.

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

Requires the proptest1 feature to be enabled.

source

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

Available on crate feature proptest1 only.

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

Requires the proptest1 feature to be enabled.

source§

impl PackageGraph

§Queries

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

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source§

impl PackageGraph

source

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.

source

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

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

source

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.

source

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.

source

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.

source

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.

source

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.

source§

impl PackageGraph

source

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

Available 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§

source§

impl Clone for PackageGraph

source§

fn clone(&self) -> PackageGraph

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for PackageGraph

source§

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

Formats the value using the given formatter. Read more
source§

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

§

type Error = Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl TryFrom<CargoMetadata> for PackageGraph

§

type Error = Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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.
source§

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

Performs the conversion.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V