Skip to main content

Crate cargo_critpath

Crate cargo_critpath 

Source
Expand description

Turn the output of a real Cargo build into a critpath_core::BuildGraph.

Two inputs are needed, and one cargo build --timings -v --offline produces both:

  • the verbose build log, which contains one rustc invocation per dirty unit and therefore states the unit set, the edge set and each edge’s kind exactly;
  • the timing report, target/cargo-timings/cargo-timing.html, which contains each unit’s wall duration and the moment it emitted its metadata.

Neither input is sufficient alone. The timing report cannot tell a library from a procedural macro, and its unblocked_units fields record only the last blocker of each unit rather than the dependency graph. The verbose log carries no timings. The details, and the measurements behind them, are in docs/cargo-data-sources.md.

let outputs = cargo_critpath::collect::from_directory(std::path::Path::new("captured"))?;
let input = cargo_critpath::parse_with_metadata(
    &outputs.verbose_log,
    &outputs.timing_html,
    outputs.cargo_metadata.as_deref(),
)?;
println!("{} units, {} edges", input.graph.len(), input.graph.edge_count());

Everything except collect takes text rather than paths, so it is testable without a filesystem.

Modules§

cli
The command line: arguments, the pipeline they drive, and the exit codes.
collect
Getting the three inputs off disk, or out of Cargo.

Structs§

BuildInput
One build, ready to analyse.
BuildMeta
Where a build’s numbers came from.
Diagnostic
Something worth telling the reader about the input, which was not bad enough to refuse.
ExternRef
One --extern argument: a dependency, and what the consumer needs of it.
Invocation
One piece of work Cargo performed, as the verbose log recorded it.
PackageIndex
Every package a workspace contains, indexed by the directory its manifest lives in.
PackageRef
A package named exactly, by a source path that contains name-version/.
TimingReport
Everything one timing report described.
TimingUnit
One entry of the report’s UNIT_DATA array.
UnblockedCheck
The result of checking the report’s unblocked_* fields against the graph the log gave.
UnblockedPair
One pair the timing report claims a dependency between.
UnitDescription
Enough of a unit’s identity to name it in an error message.
VerboseLog
Everything one verbose build log described.

Enums§

MatchMethod
How a unit’s two halves were recognised as the same unit, in decreasing order of certainty.
ParseError
A build’s output that could not be turned into a graph, and why.
Role
What a Running `…` line was doing.
Severity
How serious a diagnostic is.
TimingTarget
What the timing report says a unit is.
UnblockedSource
Which of the report’s unblocked_* fields a pair came from.

Functions§

parse
Parses one build’s verbose log and timing report into an analysable BuildInput.
parse_cargo_metadata
Reads cargo metadata --format-version 1 output.
parse_timing_report
Reads a cargo-timing.html report.
parse_verbose_log
Reads every Running `…` line out of a verbose build log.
parse_with_metadata
Parses one build’s inputs, resolving workspace-local packages through cargo metadata.