Track and query Cargo dependency graphs.
This repository contains the source code for: *
guppy: a library for performing queries on Cargo dependency graphs
guppy-summaries: a library for managing build summaries listing packages and features
target-spec: an evaluator for
Cargo.tomltarget specifications
determinator: figure out what packages changed between two revisions
hakari: manage workspace-hack packages
cargo-guppy: a command-line frontend for the
guppylibrary
guppybehaves correctly.
guppyand
cargo-guppycan be used to solve many practical problems related to dependency graphs in large Rust codebases. Some examples -- all of these are available through the
guppylibrary, and will eventually be supported in the
cargo-guppyCLI as well:
dotgraph for a subset of crates, for formatting with graphviz
Still to come:
The core
guppycode in this repository is considered mostly complete and the API is mostly stable.
We're building a number of tools on top of guppy, and those are still are under active development. Tool requirements may cause further changes in the API, but the goal will be to avoid extensive overhauls.
guppy's simulation of Cargo builds is extensively tested against upstream Cargo, and there are no known differences. Comparison testing has found a number of bugs in upstream Cargo, for example: * v2 resolver: different handling for inactive, optional dependencies based on how they're specified * v2 resolver: a proc macro being specified with the key "proc_macro" vs "proc-macro" causes different results * specifying different versions in unconditional and target-specific dependency sections causes "multiple rmeta candidates" error
cargo-guppyis extensively used by the Diem Core project.
guppyis used for several lint checks. This includes basic rules that look at every workspace package separately: * every package has fields like
authorand
licensespecified * crate names and paths should use
-instead of
_
to more complex rules about the overall dependency graph, such as: * some third-party dependencies are banned from the workspace entirely, or only from default builds * every workspace package depends on a
workspace-hackcrate (similar to rustc-workspace-hack) * for any given third-party dependency, the workspace only depends on one version of it directly (transitive dependencies to other versions are still allowed) * every workspace package is categorized as either production or test-only, and the linter checks that test-only crates are not included in production builds * support for overlay features, which allow test-only code to be: * included in crates (similar to the
#[cfg(test)]annotation) * depended on by test-only code in other crates (
#[cfg(test)]does not allow this) * but guaranteed to be excluded from production builds
In addition,
guppy-summariesis used to generate build summaries of packages and features (particularly for high-security subsets of the codebase), and changes to these sets are flagged by Diem's CI (example).
guppyis written on top of the excellent petgraph library. It is a separate codebase from
cargo, depending only on the stable
cargo metadataformat. (Some other tools in this space like
cargo-treeuse cargo internals directly.)
The minimum supported Rust version (MSRV) is 1.48.
While a crate is pre-release status (0.x.x) it may have its MSRV bumped in a patch release. Once a crate has reached 1.x, any MSRV bump will be accompanied with a new minor version.
See the CONTRIBUTING file for how to help out.
This project is available under the terms of either the Apache 2.0 license or the MIT license.