guppy

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.

Contributing

See the CONTRIBUTING file for how to help out.

License

This project is available under the terms of either the Apache 2.0 license or the MIT license.