/cargo-guppy

Track and query Cargo dependency graphs.

Primary LanguageRustApache License 2.0Apache-2.0

cargo-guppy: track and query dependency graphs

Build Status License License

This repository contains the source code for:

  • guppy: a library for performing queries on Cargo dependency graphs guppy on crates.io Documentation (latest release) Documentation (master)
  • guppy-summaries: a library for managing build summaries listing packages and features guppy-summaries on crates.io Documentation (latest release) Documentation (master)
  • cargo-guppy: a command-line frontend for the guppy library Documentation (master)
  • target-spec: an evaluator for Cargo.toml target specifications target-spec on crates.io Documentation (latest release) Documentation (master)
  • and a number of tools and test fixtures used to verify that guppy behaves correctly.

The code in this repository is in a pre-release state and is under active development.

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

This code has been written for the Libra Core project, but it may be useful for other large Rust projects.

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

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.