55 releases
0.17.8 | Oct 2, 2024 |
---|---|
0.17.6 | Jul 29, 2024 |
0.17.5 | Feb 4, 2024 |
0.17.4 | Nov 29, 2023 |
0.1.2 | Nov 26, 2019 |
#30 in Data structures
240,514 downloads per month
Used in 51 crates
(30 directly)
600KB
11K
SLoC
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 withPackageQuery::resolve
, and fine-grained control over the traversal is achieved withPackageQuery::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 FeatureSet
s 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 theproptest
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.
Dependencies
~4.5–6.5MB
~113K SLoC