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

Re-exports

• pub use errors::Error;
• pub use semver::Version;
• pub use semver::VersionReq;
• pub use serde_json::Value as JsonValue;

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

• CargoMetadata
  Deserialized Cargo metadata.
• MetadataCommand
  A builder for configuring cargo metadata invocations.
• PackageId
  An “opaque” identifier for a package.

Enums

• DependencyKind
  A descriptor for the kind of dependency.