1use core::fmt;
8use std::ffi::OsString;
9use std::io::{self, Write};
10use std::num::NonZeroU32;
11use std::path::{Path, PathBuf};
12
13use critpath_core::{analyze, Millis, Policy};
14use lexopt::ValueExt;
15
16use crate::findings;
17use crate::timings::TimingReport;
18use crate::{json, parse_with_metadata, report, ParseError};
19
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25#[non_exhaustive]
26pub enum Outcome {
27 Completed,
29 Usage,
31 Rejected,
33 ThresholdExceeded,
35}
36
37impl Outcome {
38 #[must_use]
40 pub const fn code(self) -> i32 {
41 match self {
42 Self::Completed => 0,
43 Self::Usage => 1,
44 Self::Rejected => 2,
45 Self::ThresholdExceeded => 3,
46 }
47 }
48}
49
50const HELP: &str = "\
53cargo-critpath — what to change in a Cargo build, and how much time it would save
54
55USAGE
56 cargo critpath --log <path> --timings <path> [options]
57
58 Capture the two inputs from one clean build:
59
60 cargo clean
61 cargo build --timings -v --offline 2>build.log
62 cargo critpath --log build.log --timings target/cargo-timings/cargo-timing.html
63
64REQUIRED
65 --log <path> the verbose build log: Cargo's stderr from `cargo build -v`
66 --timings <path> a `cargo-timing.html` report from the same build. Repeatable: give one
67 per clean build of the same commit and the run-to-run spread of the
68 critical path is measured, so that a saving smaller than the noise can
69 be marked as such
70
71OPTIONS
72 --metadata <path> `cargo metadata --format-version 1` output, which attributes a
73 workspace-local source path to its package exactly rather than by
74 directory name
75 --jobs <n> how many executors to analyse for. Defaults to the -j the build ran with
76 --format <f> human (default) or json. The JSON contract is documented at
77 https://github.com/eventvoid/cargo-critpath/blob/main/docs/json-schema.md
78 --policy <p> cargo-like (default), which reproduces Cargo's cost-blind ordering, or
79 longest-path, which schedules better than Cargo does. The gap between
80 them is what Cargo's ordering alone costs
81 --include-units add the per-unit array to the JSON output
82 --top <n> how many ranked units and scenarios to show (default 10)
83 --fail-if-critical-path-over <ms>
84 exit 3 if the critical path is longer than this
85 --help print this and exit
86 --version print the version and exit
87
88EXIT CODES
89 0 the analysis completed
90 1 the arguments were wrong, or a path could not be read
91 2 the input was rejected: fresh units, an unreadable report, or a build that was not
92 `cargo build`
93 3 the analysis completed and a --fail-if threshold was exceeded
94
95WHAT THIS DOES NOT DO
96 It analyses `cargo build` only, and refuses a report from `cargo check`, `cargo test` or
97 `cargo doc` by name: those are different graphs, not variations on one.
98 Every weight comes from one real build at one executor count and is not invariant to it, so
99 an absolute time for another executor count is marked unreliable rather than presented.
100 A split cannot be modelled exactly, so it is reported as an interval with its assumptions
101 printed, never as a single number.
102";
103
104struct Options {
106 log: PathBuf,
107 timings: Vec<PathBuf>,
108 metadata: Option<PathBuf>,
109 jobs: Option<NonZeroU32>,
110 format: Format,
111 policy: Policy,
112 include_units: bool,
113 top: usize,
114 fail_if_over: Option<Millis>,
115}
116
117#[derive(Clone, Copy, PartialEq, Eq)]
119enum Format {
120 Human,
121 Json,
122}
123
124enum Command {
126 Help,
127 Version,
128 Analyse(Box<Options>),
129}
130
131const OPTIONS: &str = "--log, --timings, --metadata, --jobs, --format, --policy, --include-units, \
133 --top, --fail-if-critical-path-over, --help, --version";
134
135enum UsageError {
137 Unknown(String),
138 Unexpected(String),
139 MissingValue(String),
140 BadValue {
141 option: &'static str,
142 value: String,
143 expected: &'static str,
144 },
145 Missing(&'static str),
146 Unreadable {
147 path: String,
148 detail: String,
149 },
150 MisEncoded {
152 detail: String,
153 },
154 ExecutorCountUnknown,
155}
156
157impl fmt::Display for UsageError {
158 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
159 match self {
160 Self::Unknown(option) => write!(
161 f,
162 "unknown option `{option}`. The options are: {OPTIONS}. \
163 Run `cargo critpath --help` for what each one does"
164 ),
165 Self::Unexpected(value) => write!(
166 f,
167 "unexpected argument `{value}`: this tool takes options only, apart from the \
168 `critpath` word Cargo itself inserts. The options are: {OPTIONS}"
169 ),
170 Self::MissingValue(option) => write!(
171 f,
172 "the option `{option}` needs a value and was given none. \
173 Run `cargo critpath --help` for what it expects"
174 ),
175 Self::BadValue {
176 option,
177 value,
178 expected,
179 } => write!(
180 f,
181 "`{value}` is not a usable value for `{option}`: {expected}"
182 ),
183 Self::Missing(option) => write!(
184 f,
185 "`{option}` is required and was not given. \
186 Capture both inputs from one clean build with \
187 `cargo build --timings -v --offline 2>build.log`, then pass the log to `--log` \
188 and `target/cargo-timings/cargo-timing.html` to `--timings`"
189 ),
190 Self::Unreadable { path, detail } => write!(
191 f,
192 "cannot read `{path}`: {detail}. \
193 Check the path, and that the build that was supposed to write it completed"
194 ),
195 Self::MisEncoded { detail } => write!(f, "{detail}"),
198 Self::ExecutorCountUnknown => write!(
199 f,
200 "the timing report does not record what `-j` the build ran with, so there is no \
201 executor count to analyse for. Pass `--jobs <n>` to choose one"
202 ),
203 }
204 }
205}
206
207impl From<lexopt::Error> for UsageError {
208 fn from(error: lexopt::Error) -> Self {
209 match error {
210 lexopt::Error::UnexpectedOption(option) => Self::Unknown(option),
211 lexopt::Error::UnexpectedArgument(value) => {
212 Self::Unexpected(value.to_string_lossy().into_owned())
213 }
214 lexopt::Error::MissingValue { option } => {
215 Self::MissingValue(option.unwrap_or_else(|| "an option".to_owned()))
216 }
217 other => Self::Unknown(other.to_string()),
218 }
219 }
220}
221
222pub fn run<I>(args: I, out: &mut dyn Write, err: &mut dyn Write) -> Outcome
234where
235 I: IntoIterator,
236 I::Item: Into<OsString>,
237{
238 let command = match parse(args) {
239 Ok(command) => command,
240 Err(problem) => {
241 let _ = writeln!(err, "error: {problem}");
242 return Outcome::Usage;
243 }
244 };
245 match command {
246 Command::Help => {
247 let _ = write!(out, "{HELP}");
248 Outcome::Completed
249 }
250 Command::Version => {
251 let _ = writeln!(out, "cargo-critpath {}", env!("CARGO_PKG_VERSION"));
252 Outcome::Completed
253 }
254 Command::Analyse(options) => analyse(&options, out, err),
255 }
256}
257
258fn parse<I>(args: I) -> Result<Command, UsageError>
259where
260 I: IntoIterator,
261 I::Item: Into<OsString>,
262{
263 let mut log: Option<PathBuf> = None;
264 let mut timings: Vec<PathBuf> = Vec::new();
265 let mut metadata: Option<PathBuf> = None;
266 let mut jobs: Option<NonZeroU32> = None;
267 let mut format = Format::Human;
268 let mut policy = Policy::CargoLike;
269 let mut include_units = false;
270 let mut top = 10usize;
271 let mut fail_if_over: Option<Millis> = None;
272 let mut seen_subcommand = false;
273
274 let mut parser = lexopt::Parser::from_iter(args);
275 while let Some(argument) = parser.next()? {
276 match argument {
277 lexopt::Arg::Long("log") => log = Some(PathBuf::from(parser.value()?)),
278 lexopt::Arg::Long("timings") => timings.push(PathBuf::from(parser.value()?)),
279 lexopt::Arg::Long("metadata") => metadata = Some(PathBuf::from(parser.value()?)),
280 lexopt::Arg::Long("jobs") => {
281 let raw = parser.value()?.string()?;
282 jobs = Some(raw.parse().ok().and_then(NonZeroU32::new).ok_or(
283 UsageError::BadValue {
284 option: "--jobs",
285 value: raw.clone(),
286 expected: "it must be a whole number of executors, at least 1",
287 },
288 )?);
289 }
290 lexopt::Arg::Long("format") => {
291 let raw = parser.value()?.string()?;
292 format = match raw.as_str() {
293 "human" => Format::Human,
294 "json" => Format::Json,
295 _ => {
296 return Err(UsageError::BadValue {
297 option: "--format",
298 value: raw,
299 expected: "the formats are `human` and `json`",
300 })
301 }
302 };
303 }
304 lexopt::Arg::Long("policy") => {
305 let raw = parser.value()?.string()?;
306 policy = match raw.as_str() {
307 "cargo-like" => Policy::CargoLike,
308 "longest-path" => Policy::LongestPath,
309 _ => {
310 return Err(UsageError::BadValue {
311 option: "--policy",
312 value: raw,
313 expected: "the policies are `cargo-like` and `longest-path`",
314 })
315 }
316 };
317 }
318 lexopt::Arg::Long("include-units") => include_units = true,
319 lexopt::Arg::Long("top") => {
320 let raw = parser.value()?.string()?;
321 top = raw.parse().map_err(|_| UsageError::BadValue {
322 option: "--top",
323 value: raw.clone(),
324 expected: "it must be a whole number of entries, and may be 0",
325 })?;
326 }
327 lexopt::Arg::Long("fail-if-critical-path-over") => {
328 let raw = parser.value()?.string()?;
329 let ms: u64 = raw.parse().map_err(|_| UsageError::BadValue {
330 option: "--fail-if-critical-path-over",
331 value: raw.clone(),
332 expected: "it must be a whole number of milliseconds",
333 })?;
334 fail_if_over = Some(Millis::new(ms));
335 }
336 lexopt::Arg::Long("help") => return Ok(Command::Help),
337 lexopt::Arg::Long("version") => return Ok(Command::Version),
338 lexopt::Arg::Value(value) if !seen_subcommand && value == *"critpath" => {
341 seen_subcommand = true;
342 }
343 lexopt::Arg::Value(value) => {
344 return Err(UsageError::Unexpected(value.to_string_lossy().into_owned()))
345 }
346 lexopt::Arg::Long(name) => return Err(UsageError::Unknown(format!("--{name}"))),
347 lexopt::Arg::Short(letter) => return Err(UsageError::Unknown(format!("-{letter}"))),
348 }
349 }
350
351 let log = log.ok_or(UsageError::Missing("--log"))?;
352 if timings.is_empty() {
353 return Err(UsageError::Missing("--timings"));
354 }
355 Ok(Command::Analyse(Box::new(Options {
356 log,
357 timings,
358 metadata,
359 jobs,
360 format,
361 policy,
362 include_units,
363 top,
364 fail_if_over,
365 })))
366}
367
368fn analyse(options: &Options, out: &mut dyn Write, err: &mut dyn Write) -> Outcome {
369 let log = match read(&options.log) {
370 Ok(text) => text,
371 Err(problem) => return usage(err, &problem),
372 };
373 let metadata = match options.metadata.as_deref() {
374 Some(path) => match read(path) {
375 Ok(text) => Some(text),
376 Err(problem) => return usage(err, &problem),
377 },
378 None => None,
379 };
380 let mut reports = Vec::with_capacity(options.timings.len());
381 for path in &options.timings {
382 match read(path) {
383 Ok(text) => reports.push(text),
384 Err(problem) => return usage(err, &problem),
385 }
386 }
387
388 for text in &reports {
392 let report = match crate::parse_timing_report(text) {
393 Ok(report) => report,
394 Err(problem) => return rejected(err, &problem),
395 };
396 if let Some(subcommand) = subcommand_of(&report) {
397 let _ = writeln!(
398 err,
399 "error: this timing report is from `{subcommand}`, which this tool does not \
400 analyse. Only `cargo build` is supported, because the other subcommands build \
401 genuinely different graphs: on one measured project, `cargo build` and \
402 `cargo check` shared exactly one unit on their critical paths. Capture a build \
403 with `cargo clean && cargo build --timings -v --offline 2>build.log`"
404 );
405 return Outcome::Rejected;
406 }
407 }
408
409 let mut builds = Vec::with_capacity(reports.len());
410 for text in &reports {
411 match parse_with_metadata(&log, text, metadata.as_deref()) {
412 Ok(build) => builds.push(build),
413 Err(problem) => return rejected(err, &problem),
414 }
415 }
416 let Some(primary) = builds.first() else {
417 return usage(err, &UsageError::Missing("--timings"));
418 };
419
420 let executors = match options
421 .jobs
422 .or_else(|| primary.build.jobs.and_then(NonZeroU32::new))
423 {
424 Some(executors) => executors,
425 None => return usage(err, &UsageError::ExecutorCountUnknown),
426 };
427 let samples: Vec<Millis> = builds
428 .iter()
429 .map(|build| analyze(&build.graph).critical_path_len())
430 .collect();
431
432 let findings = findings::assemble(primary, &samples, executors, options.policy, options.top);
433 let written = match options.format {
434 Format::Human => report::write(out, &findings),
435 Format::Json => json::write(out, &findings, options.include_units),
436 };
437 if let Err(problem) = written {
438 let _ = writeln!(err, "error: cannot write the report: {problem}");
439 return Outcome::Usage;
440 }
441
442 match options.fail_if_over {
443 Some(limit) if findings.baseline.critical_path > limit => {
444 let _ = writeln!(
445 err,
446 "error: the critical path is {} against the {limit} limit given by \
447 --fail-if-critical-path-over",
448 findings.baseline.critical_path
449 );
450 Outcome::ThresholdExceeded
451 }
452 _ => Outcome::Completed,
453 }
454}
455
456fn subcommand_of(report: &TimingReport) -> Option<&'static str> {
462 const MARKERS: [(&str, &str); 5] = [
463 ("(doc test)", "cargo test"),
464 ("(test)", "cargo test"),
465 ("(bench)", "cargo bench"),
466 ("(check)", "cargo check"),
467 ("(doc)", "cargo doc"),
468 ];
469 report.units.iter().find_map(|unit| {
470 let label = unit.target.label();
471 MARKERS
472 .iter()
473 .find(|(marker, _)| label.ends_with(marker))
474 .map(|(_, command)| *command)
475 })
476}
477
478fn read(path: &Path) -> Result<String, UsageError> {
479 crate::collect::read_text(path).map_err(|problem| {
480 if problem.kind() == io::ErrorKind::InvalidData {
481 UsageError::MisEncoded {
482 detail: problem.to_string(),
483 }
484 } else {
485 UsageError::Unreadable {
486 path: path.display().to_string(),
487 detail: problem.to_string(),
488 }
489 }
490 })
491}
492
493fn usage(err: &mut dyn Write, problem: &UsageError) -> Outcome {
494 let _ = writeln!(err, "error: {problem}");
495 match problem {
496 UsageError::MisEncoded { .. } => Outcome::Rejected,
501 _ => Outcome::Usage,
502 }
503}
504
505fn rejected(err: &mut dyn Write, problem: &ParseError) -> Outcome {
506 let _ = writeln!(err, "error: {problem}");
507 Outcome::Rejected
508}