Crate guppy

source ·
Expand description

Track and query Cargo dependency graphs.

guppy provides a Rust interface to run queries over Cargo dependency graphs. guppy parses the output of cargo metadata, then presents a graph interface over it.

§Types and lifetimes

The central structure exposed by guppy is PackageGraph. This represents a directed (though not necessarily acyclic) graph where every node is a package and every edge represents a dependency.

Other types borrow data from a PackageGraph and have a 'g lifetime parameter indicating that. A lifetime parameter named 'g always indicates that data is borrowed from a PackageGraph.

PackageMetadata contains information about individual packages, such as the data in the [package] section.

For traversing the graph, guppy provides a few types:

  • PackageLink represents both ends of a dependency edge, along with details about the dependency (whether it is dev-only, platform-specific, and so on).
  • PackageQuery represents the input parameters to a dependency traversal: a set of packages and a direction. A traversal is performed with PackageQuery::resolve, and fine-grained control over the traversal is achieved with PackageQuery::resolve_with_fn.
  • PackageSet represents the result of a graph traversal. This struct provides several methods to iterate over packages.

For some operations, guppy builds an auxiliary FeatureGraph the first time it is required. Every node in a FeatureGraph is a combination of a package and a feature declared in it, and every edge is a feature dependency.

For traversing the feature graph, guppy provides the analogous FeatureQuery and FeatureSet types.

FeatureSet also has an into_cargo_set method, to simulate Cargo builds. This method produces a CargoSet, which is essentially two FeatureSets along with some more useful information.

guppy’s data structures are immutable, with some internal caches. All of guppy’s types are Send + Sync, and all lifetime parameters are covariant.

§Optional features

  • proptest1: Support for property-based testing using the proptest framework.
  • rayon1: Support for parallel iterators through Rayon (preliminary work so far, more parallel iterators to be added in the future).
  • summaries: Support for writing out build summaries.

§Examples

Print out all direct dependencies of a package:

use guppy::{CargoMetadata, PackageId};

// `guppy` accepts `cargo metadata` JSON output. Use a pre-existing fixture for these examples.
let metadata = CargoMetadata::parse_json(include_str!("../../fixtures/small/metadata1.json")).unwrap();
let package_graph = metadata.build_graph().unwrap();

// `guppy` provides several ways to get hold of package IDs. Use a pre-defined one for this
// example.
let package_id = PackageId::new("testcrate 0.1.0 (path+file:///fakepath/testcrate)");

// The `metadata` method returns information about the package, or `None` if the package ID
// wasn't recognized.
let package = package_graph.metadata(&package_id).unwrap();

// `direct_links` returns all direct dependencies of a package.
for link in package.direct_links() {
    // A dependency link contains `from()`, `to()` and information about the specifics of the
    // dependency.
    println!("direct dependency: {}", link.to().id());
}

For more examples, see the examples directory.

Re-exports§

Modules§

  • errors
    Contains types that describe errors and warnings that guppy methods can return.
  • graph
    Entry point for analyzing Cargo dependency graphs.
  • platform
    Support for dependencies that are only enabled on some platforms.

Structs§

Enums§