cargo_critpath/lib.rs
1//! Turn the output of a real Cargo build into a [`critpath_core::BuildGraph`].
2//!
3//! Two inputs are needed, and one `cargo build --timings -v --offline` produces both:
4//!
5//! - the **verbose build log**, which contains one `rustc` invocation per dirty unit and therefore
6//! states the unit set, the edge set and each edge's kind exactly;
7//! - the **timing report**, `target/cargo-timings/cargo-timing.html`, which contains each unit's
8//! wall duration and the moment it emitted its metadata.
9//!
10//! Neither input is sufficient alone. The timing report cannot tell a library from a procedural
11//! macro, and its `unblocked_units` fields record only the last blocker of each unit rather than the
12//! dependency graph. The verbose log carries no timings. The details, and the measurements behind
13//! them, are in `docs/cargo-data-sources.md`.
14//!
15//! ```no_run
16//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
17//! let outputs = cargo_critpath::collect::from_directory(std::path::Path::new("captured"))?;
18//! let input = cargo_critpath::parse_with_metadata(
19//! &outputs.verbose_log,
20//! &outputs.timing_html,
21//! outputs.cargo_metadata.as_deref(),
22//! )?;
23//! println!("{} units, {} edges", input.graph.len(), input.graph.edge_count());
24//! # Ok(())
25//! # }
26//! ```
27//!
28//! Everything except [`collect`] takes text rather than paths, so it is testable without a
29//! filesystem.
30#![forbid(unsafe_code)]
31
32pub mod cli;
33pub mod collect;
34mod error;
35mod findings;
36mod input;
37mod json;
38mod metadata;
39mod report;
40mod timings;
41mod units;
42mod verbose;
43
44pub use error::{ParseError, UnitDescription};
45pub use input::{
46 BuildInput, BuildMeta, Diagnostic, Severity, UnblockedCheck, UnblockedPair, UnblockedSource,
47};
48pub use metadata::{parse as parse_cargo_metadata, PackageIndex};
49pub use timings::{parse as parse_timing_report, TimingReport, TimingTarget, TimingUnit};
50pub use units::MatchMethod;
51pub use verbose::{
52 parse as parse_verbose_log, ExternRef, Invocation, PackageRef, Role, VerboseLog,
53};
54
55/// Parses one build's verbose log and timing report into an analysable [`BuildInput`].
56///
57/// This is the entry point most callers want. See [`parse_with_metadata`] for the workspaces where
58/// it is not enough.
59///
60/// # Errors
61///
62/// Returns [`ParseError`] if either input cannot be parsed, if the build was not a clean full build,
63/// or if the two inputs describe different sets of units. No graph is ever built from a partial unit
64/// set: an unmatched unit is a refusal, not a warning.
65pub fn parse(verbose_log: &str, timing_html: &str) -> Result<BuildInput, ParseError> {
66 parse_with_metadata(verbose_log, timing_html, None)
67}
68
69/// Parses one build's inputs, resolving workspace-local packages through `cargo metadata`.
70///
71/// A `rustc` invocation identifies its unit by a source path. For a registry crate that path
72/// contains `name-version/` and the package is known exactly. For a workspace-local crate it does
73/// not. `cargo metadata --format-version 1` gives every package's `manifest_path`, so a source path
74/// can be attributed to a package by longest-prefix match on the manifest directories — exactly,
75/// with no heuristic.
76///
77/// Passing `None` falls back to the crate name and then to the crate's own directory name, which is
78/// right for most workspaces and wrong for some: `bevy` keeps several distinct procedural-macro
79/// packages in directories all named `macros`. Where the fallback cannot separate two units, the
80/// parse fails and the error says that `cargo metadata` output would resolve it.
81///
82/// # Errors
83///
84/// As [`parse`], plus [`ParseError::Metadata`] if `cargo_metadata` is not the expected JSON.
85pub fn parse_with_metadata(
86 verbose_log: &str,
87 timing_html: &str,
88 cargo_metadata: Option<&str>,
89) -> Result<BuildInput, ParseError> {
90 let log = verbose::parse(verbose_log)?;
91 let report = timings::parse(timing_html)?;
92 let packages = match cargo_metadata {
93 Some(text) => Some(metadata::parse(text)?),
94 None => None,
95 };
96 input::assemble(&log, &report, packages.as_ref())
97}