cargo-guppy: track and query dependency graphs

This repository contains the source code for:

• guppy: a library for performing queries on Cargo dependency graphs

• libraries used by guppy:

  • guppy-summaries: a library for managing build summaries listing packages and features
  • target-spec: an evaluator for Cargo.toml target specifications

• integrations for target-spec:

  • target-spec-miette: allows converting target-spec errors to miette diagnostics

• tools built on top of guppy:

  • determinator: figure out what packages changed between two revisions
  • cargo-hakari: a command-line tool to manage workspace-hack packages
    • available in library form as hakari
  • cargo-guppy: an experimental command-line frontend for guppy

• and a number of internal tools and test fixtures used to verify that guppy behaves correctly.

Use cases

guppy and cargo-guppy can be used to solve many practical problems related to dependency graphs in large Rust codebases. Some examples -- all of these are available through the guppy library, and will eventually be supported in the cargo-guppy CLI as well:

• track existing dependencies for a crate or workspace
• query direct or transitive dependencies of a subset of packages — useful when some packages have greater assurance or reliability requirements
• figure out what's causing a particular crate to be included as a dependency
• iterate over reverse dependencies of a crate in topological order
• iterate over some or all links (edges) in a dependency graph, querying if the link is a build, dev or regular dependency
• filter out dev-only dependencies while performing queries
• perform queries based on Cargo features
• simulate Cargo builds and return what packages and features would be built by it
• evaluate target specs for platform-specific dependencies
• generate summary files for Cargo builds, which can be used to:
  • receive CI feedback if a dependency is added, updated or removed, or if new features are added
  • receive CI feedback if a package is added to a high-assurance subset, or if any new features are enabled in an existing package in that subset. This can be used to flag those changes for extra scrutiny.
• print out a dot graph for a subset of crates, for formatting with graphviz

Still to come:

• a command-line query language

Development status

The core guppy code in this repository is considered mostly complete and the API is mostly stable.

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

Design

guppy is written on top of the excellent petgraph library. It is a separate codebase from cargo, depending only on the stable cargo metadata format. (Some other tools in this space like cargo-tree use cargo internals directly.)

Minimum supported Rust version

The minimum supported Rust version (MSRV) is Rust 1.86.

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.

At any given time, at least the last 3 versions of Rust will be supported. For target-spec, at least the last 6 months of stable Rust releases will be supported.

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.