cargo_critpath/verbose.rs
1//! Reading the structure of a build out of `cargo build -v`.
2//!
3//! With `-v` Cargo prints one `` Running `…` `` line per piece of work it actually performs: a
4//! `rustc` invocation for every dirty compilation unit, and a bare execution of the compiled
5//! binary for every build script it runs. Those lines are the whole unit set and, through their
6//! `--extern` arguments, the whole edge set.
7
8use critpath_core::{EdgeKind, UnitKind};
9
10use crate::error::ParseError;
11
12/// What a `` Running `…` `` line was doing.
13#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
14pub enum Role {
15 /// A `rustc` invocation compiling one unit.
16 Compile,
17 /// Execution of an already-compiled build script.
18 BuildScriptRun,
19}
20
21/// A package named exactly, by a source path that contains `name-version/`.
22#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
23#[non_exhaustive]
24pub struct PackageRef {
25 /// The package name, as it appears in the registry path.
26 pub name: String,
27 /// The package version, as it appears in the registry path.
28 pub version: String,
29}
30
31/// One `--extern` argument: a dependency, and what the consumer needs of it.
32#[derive(Clone, Debug, PartialEq, Eq)]
33#[non_exhaustive]
34pub struct ExternRef {
35 /// The name the consumer knows the dependency by.
36 pub name: String,
37 /// The artifact's file extension, kept for diagnostics.
38 pub extension: String,
39 /// What the consumer needs before it can start: `.rmeta` is metadata, anything else is a
40 /// complete build.
41 pub edge: EdgeKind,
42 /// The producer's `-C extra-filename`, including its leading dash, taken from the artifact's
43 /// file name. Edges resolve by this rather than by name, because names are ambiguous across
44 /// versions and across host and target instances of one package.
45 pub producer: Option<String>,
46}
47
48/// One piece of work Cargo performed, as the verbose log recorded it.
49#[derive(Clone, Debug, PartialEq, Eq)]
50#[non_exhaustive]
51pub struct Invocation {
52 /// Position among the `Running` lines, counted from zero. Cargo prints these as it starts each
53 /// job, so the order approximates the order the timing report lists units in.
54 pub position: usize,
55 /// Whether this compiled something or ran a build script.
56 pub role: Role,
57 /// The `--crate-name`, or empty for a build-script execution.
58 pub crate_name: String,
59 /// Every `--crate-type`. Cargo writes one for a binary too; empty is the fallback, and is read
60 /// as something that links, since assuming a library would drop a closure requirement.
61 pub crate_types: Vec<String>,
62 /// The `--emit` list.
63 pub emits: Vec<String>,
64 /// Whether the unit emits metadata, which is exactly when a dependent may start against it
65 /// before it has finished.
66 pub pipelined: bool,
67 /// The `-C extra-filename`, including its leading dash. This is the unit's identity: every
68 /// `--extern` path that names this unit's artifact embeds it.
69 pub extra_filename: Option<String>,
70 /// The `-C metadata` hash, which distinguishes two instances of one package that differ only
71 /// in features or in being built for the host rather than the target.
72 pub metadata_hash: Option<String>,
73 /// Every `--extern` that named an artifact. `--extern proc_macro`, which names the compiler's
74 /// own crate and has no path, is not one of these.
75 pub externs: Vec<ExternRef>,
76 /// The source file the invocation compiled, exactly as it appeared. Cargo writes this relative
77 /// to the workspace root for a workspace-local target and absolute for a registry one.
78 pub source_path: String,
79 /// The features the unit was compiled with, sorted, recovered from `--cfg feature="…"`.
80 pub features: Vec<String>,
81 /// The package, where the source path stated it exactly.
82 pub registry_package: Option<PackageRef>,
83 /// The package's own directory name, for a workspace-local target whose source path did not.
84 /// A heuristic: a package need not be named after its directory.
85 pub directory_package: Option<String>,
86 /// The package name, for a build-script compilation or execution, taken from the
87 /// `target/<profile>/build/<package>-<hash>` directory Cargo gives it. Exact.
88 pub run_package: Option<String>,
89 /// The compiled build script's `-C extra-filename`, including its leading dash, for a
90 /// build-script execution. This ties the run to the compilation exactly.
91 pub run_artifact: Option<String>,
92 /// What sort of work this is.
93 pub kind: UnitKind,
94 /// Whether the unit needs its whole transitive dependency closure to be fully built, which is
95 /// Cargo's `requires_upstream_objects`.
96 pub requires_full_closure: bool,
97}
98
99/// Everything one verbose build log described.
100#[derive(Clone, Debug, PartialEq, Eq)]
101#[non_exhaustive]
102pub struct VerboseLog {
103 /// The work Cargo performed, in the order it started it.
104 pub invocations: Vec<Invocation>,
105 /// `Running` lines that were neither a `rustc` invocation nor a build-script execution, kept
106 /// verbatim so that they can be named if they turn out to matter.
107 pub unrecognised: Vec<String>,
108}
109
110/// Reads every `` Running `…` `` line out of a verbose build log.
111///
112/// # Errors
113///
114/// [`ParseError::NotUtf8`] if the text holds NUL characters, which means it was decoded from
115/// UTF-16 rather than the UTF-8 Cargo wrote; [`ParseError::NoInvocations`] if the log holds none,
116/// which means it was captured without `-v` or from a build that had nothing to do; and
117/// [`ParseError::UnbalancedQuoting`] if a line is cut off inside a quoted argument.
118pub fn parse(text: &str) -> Result<VerboseLog, ParseError> {
119 crate::error::reject_wide_text(text, "build log")?;
120 let mut invocations = Vec::new();
121 let mut unrecognised = Vec::new();
122
123 for command in commands(text) {
124 let argv = split_command(&command).ok_or_else(|| ParseError::UnbalancedQuoting {
125 line: truncate(&command),
126 })?;
127 let position = invocations.len();
128 match classify(&argv, position) {
129 Some(invocation) => invocations.push(invocation),
130 None => unrecognised.push(command),
131 }
132 }
133
134 if invocations.is_empty() {
135 return Err(ParseError::NoInvocations);
136 }
137 Ok(VerboseLog {
138 invocations,
139 unrecognised,
140 })
141}
142
143/// The text between the backticks of every `Running` line.
144///
145/// A command normally occupies one line, but an argument may contain a newline, so a line whose
146/// closing backtick is missing is continued into the following lines.
147fn commands(text: &str) -> Vec<String> {
148 const MARKER: &str = "Running `";
149 let mut out = Vec::new();
150 let mut pending: Option<String> = None;
151
152 for raw in text.lines() {
153 let line = raw.strip_suffix('\r').unwrap_or(raw);
154 match pending.take() {
155 Some(mut open) => {
156 open.push('\n');
157 match line.strip_suffix('`') {
158 Some(rest) => {
159 open.push_str(rest);
160 out.push(open);
161 }
162 None => {
163 open.push_str(line);
164 pending = Some(open);
165 }
166 }
167 }
168 None => {
169 let trimmed = line.trim_start();
170 let Some(rest) = trimmed.strip_prefix(MARKER) else {
171 continue;
172 };
173 match rest.strip_suffix('`') {
174 Some(command) => out.push(command.to_owned()),
175 None => pending = Some(rest.to_owned()),
176 }
177 }
178 }
179 }
180 // A command left open at end of input is still worth reporting; the caller will fail on it.
181 if let Some(open) = pending {
182 out.push(open);
183 }
184 out
185}
186
187/// Splits a command into arguments, undoing exactly the escaping Cargo applied.
188///
189/// Cargo renders each argument through one escaper, and which one depends on the platform the log
190/// was captured on rather than the one reading it. Both have to be undone, and the two disagree
191/// about backslashes, so neither "a backslash escapes the next character" nor "a backslash is
192/// literal" is right on its own:
193///
194/// - The Unix escaper wraps the argument in single quotes, and renders `'` as `'\''` and `!` as
195/// `'\!'` — closing the quotes, escaping the character, reopening. So outside quotes a backslash
196/// is meaningful, but only ever before one of those two characters.
197/// - The Windows escaper wraps the argument in double quotes and doubles a backslash only where it
198/// precedes a quote. So inside quotes a lone backslash is a path separator, not an escape.
199///
200/// Anything else is a literal backslash, which is what every path separator in a Windows log is.
201///
202/// Returns `None` if a quote is left open, because the alternative is to invent arguments.
203fn split_command(command: &str) -> Option<Vec<String>> {
204 let mut args = Vec::new();
205 let mut current = String::new();
206 let mut started = false;
207 let mut chars = command.chars();
208
209 while let Some(c) = chars.next() {
210 match c {
211 ' ' | '\t' | '\n' => {
212 if started {
213 args.push(core::mem::take(&mut current));
214 started = false;
215 }
216 }
217 '\'' => {
218 started = true;
219 loop {
220 match chars.next() {
221 Some('\'') => break,
222 Some(inner) => current.push(inner),
223 None => return None,
224 }
225 }
226 }
227 '"' => {
228 started = true;
229 loop {
230 match chars.next() {
231 Some('"') => break,
232 // Only a quote or another backslash was escaped. Anything else is a
233 // separator in a Windows path and both characters are kept.
234 Some('\\') => match chars.next() {
235 Some(escaped @ ('"' | '\\')) => current.push(escaped),
236 Some(literal) => {
237 current.push('\\');
238 current.push(literal);
239 }
240 None => return None,
241 },
242 Some(inner) => current.push(inner),
243 None => return None,
244 }
245 }
246 }
247 // Outside quotes only an apostrophe or an exclamation mark is ever escaped, those being
248 // the two characters the Unix escaper closes the quotes around.
249 '\\' => {
250 started = true;
251 match chars.next() {
252 Some(escaped @ ('\'' | '!')) => current.push(escaped),
253 Some(literal) => {
254 current.push('\\');
255 current.push(literal);
256 }
257 None => return None,
258 }
259 }
260 other => {
261 started = true;
262 current.push(other);
263 }
264 }
265 }
266 if started {
267 args.push(current);
268 }
269 Some(args)
270}
271
272/// Decides what a split command was, and reads out everything the graph needs.
273fn classify(argv: &[String], position: usize) -> Option<Invocation> {
274 if let Some(first) = argv.first() {
275 if file_stem(first) == "build-script-build" {
276 let (package, artifact) = split_build_directory(parent_of(first));
277 return Some(Invocation {
278 position,
279 role: Role::BuildScriptRun,
280 crate_name: String::new(),
281 crate_types: Vec::new(),
282 emits: Vec::new(),
283 pipelined: false,
284 extra_filename: None,
285 metadata_hash: None,
286 externs: Vec::new(),
287 source_path: String::new(),
288 features: Vec::new(),
289 registry_package: None,
290 directory_package: None,
291 run_package: package,
292 run_artifact: artifact,
293 // A build-script execution is not a compilation. It needs its own executable, and
294 // that executable is a binary, so it already waits for its own whole closure.
295 // Requiring the closure again here would constrain nothing and would be wrong in
296 // principle: running a program does not link anything.
297 kind: UnitKind::BuildScriptRun,
298 requires_full_closure: false,
299 });
300 }
301 }
302
303 let compiler = argv.iter().position(|a| file_stem(a) == "rustc")?;
304 let args = argv.get(compiler.checked_add(1)?..)?;
305
306 let crate_name = value_of(args, "--crate-name")?.to_owned();
307 let crate_types: Vec<String> = values_of(args, "--crate-type");
308 let emits: Vec<String> = value_of(args, "--emit")
309 .unwrap_or_default()
310 .split(',')
311 .filter(|s| !s.is_empty())
312 .map(str::to_owned)
313 .collect();
314 let source_path = args
315 .iter()
316 .find(|a| a.ends_with(".rs"))
317 .cloned()
318 .unwrap_or_default();
319
320 let codegen: Vec<&str> = values_of_borrowed(args, "-C");
321 let extra_filename = codegen
322 .iter()
323 .find_map(|v| v.strip_prefix("extra-filename="))
324 .map(str::to_owned);
325 let metadata_hash = codegen
326 .iter()
327 .find_map(|v| v.strip_prefix("metadata="))
328 .map(str::to_owned);
329
330 let mut features: Vec<String> = values_of_borrowed(args, "--cfg")
331 .iter()
332 .filter_map(|v| {
333 v.strip_prefix("feature=\"")
334 .and_then(|v| v.strip_suffix('"'))
335 })
336 .map(str::to_owned)
337 .collect();
338 features.sort();
339 features.dedup();
340
341 let externs = values_of_borrowed(args, "--extern")
342 .iter()
343 .filter_map(|spec| extern_ref(spec))
344 .collect();
345
346 let out_dir = value_of(args, "--out-dir").unwrap_or_default();
347 let (build_package, _) = split_build_directory(out_dir);
348 // Cargo compiles a build script into `target/<profile>/build/<package>-<hash>` and everything
349 // else into `target/<profile>/deps`, so the output directory identifies a build script exactly.
350 // Its `--crate-name` does not: it is `build_script_build` only when the script is called
351 // `build.rs`.
352 let is_build_script = build_package.is_some();
353 let has_test_harness = args.iter().any(|a| a == "--test" || a == "--bench");
354
355 let (kind, requires_full_closure) = if is_build_script {
356 (UnitKind::BuildScriptCompile, true)
357 } else if has_test_harness {
358 (UnitKind::Test, true)
359 } else if crate_types.iter().any(|t| t == "proc-macro") {
360 (UnitKind::ProcMacro, true)
361 } else if crate_types.is_empty() || crate_types.iter().any(|t| t == "bin") {
362 (UnitKind::Bin, true)
363 } else if crate_types.iter().all(|t| t == "lib" || t == "rlib") {
364 // Cargo's own rule, `mode.is_any_test() || !matches!(crate_type, Lib | Rlib)`: a plain
365 // library is the only thing that can be produced from its dependencies' metadata alone.
366 (UnitKind::Lib, false)
367 } else {
368 (UnitKind::Other, true)
369 };
370
371 Some(Invocation {
372 position,
373 role: Role::Compile,
374 pipelined: emits.iter().any(|e| e == "metadata"),
375 registry_package: registry_package(&source_path),
376 directory_package: directory_package(&source_path),
377 run_package: build_package,
378 run_artifact: None,
379 crate_name,
380 crate_types,
381 emits,
382 extra_filename,
383 metadata_hash,
384 externs,
385 source_path,
386 features,
387 kind,
388 requires_full_closure,
389 })
390}
391
392/// One `--extern name=path` argument. `--extern proc_macro` has no path and names the compiler's
393/// own crate rather than a unit of this build, so it yields nothing.
394fn extern_ref(spec: &str) -> Option<ExternRef> {
395 let (name, path) = spec.split_once('=')?;
396 let file = file_name(path);
397 let (stem, extension) = match file.rsplit_once('.') {
398 Some((stem, extension)) => (stem, extension),
399 None => (file, ""),
400 };
401 Some(ExternRef {
402 name: name.to_owned(),
403 extension: extension.to_owned(),
404 // `.rmeta` is the only artifact a consumer can start against before its producer has
405 // finished. `.rlib`, `.dylib`, `.so` and anything unfamiliar all mean a complete build,
406 // which is the conservative reading.
407 edge: if extension == "rmeta" {
408 EdgeKind::Metadata
409 } else {
410 EdgeKind::Full
411 },
412 producer: trailing_hash(stem).map(str::to_owned),
413 })
414}
415
416/// `target/<profile>/build/<package>-<hash>` split into its package name and the hash, which is the
417/// compiled build script's own `-C extra-filename`.
418fn split_build_directory(dir: &str) -> (Option<String>, Option<String>) {
419 if file_name(parent_of(dir)) != "build" {
420 return (None, None);
421 }
422 let leaf = file_name(dir);
423 match trailing_hash(leaf) {
424 Some(hash) => {
425 let name = leaf.get(..leaf.len().saturating_sub(hash.len()));
426 (name.map(str::to_owned), Some(hash.to_owned()))
427 }
428 None => (None, None),
429 }
430}
431
432/// The `-HASH` suffix Cargo appends to an artifact's file stem, if there is one.
433fn trailing_hash(stem: &str) -> Option<&str> {
434 let dash = stem.rfind('-')?;
435 let hash = stem.get(dash..)?;
436 let digits = hash.get(1..)?;
437 if digits.len() >= 8 && digits.chars().all(|c| c.is_ascii_hexdigit()) {
438 Some(hash)
439 } else {
440 None
441 }
442}
443
444/// The package a registry or git source path names: `…/name-1.2.3/src/lib.rs`.
445fn registry_package(source: &str) -> Option<PackageRef> {
446 for component in components(source) {
447 let Some(dash) = component.rfind('-') else {
448 continue;
449 };
450 let (name, version) = (
451 component.get(..dash)?,
452 component.get(dash.saturating_add(1)..)?,
453 );
454 if name.is_empty() || !looks_like_version(version) {
455 continue;
456 }
457 return Some(PackageRef {
458 name: name.to_owned(),
459 version: version.to_owned(),
460 });
461 }
462 None
463}
464
465/// Whether a path component's tail is a version: three dot-separated numbers, then anything.
466fn looks_like_version(text: &str) -> bool {
467 let mut parts = text.split('.');
468 let (Some(major), Some(minor), Some(patch)) = (parts.next(), parts.next(), parts.next()) else {
469 return false;
470 };
471 let numeric = |s: &str| !s.is_empty() && s.chars().all(|c| c.is_ascii_digit());
472 let patch_number = patch.split(['-', '+']).next().unwrap_or_default();
473 numeric(major) && numeric(minor) && numeric(patch_number)
474}
475
476/// The directory a workspace-local target's package most likely lives in: the source path with any
477/// `src`, `bin`, `examples`, `tests` or `benches` component stripped from its tail.
478fn directory_package(source: &str) -> Option<String> {
479 let mut parts: Vec<&str> = components(parent_of(source)).collect();
480 while matches!(
481 parts.last().copied(),
482 Some("src" | "bin" | "examples" | "tests" | "benches")
483 ) {
484 parts.pop();
485 }
486 parts.last().map(|s| (*s).to_owned())
487}
488
489/// A path's components, whichever separator it uses. Cargo writes native separators, and a log
490/// captured on Windows is analysed on Windows, but a fixture is read on every platform.
491fn components(path: &str) -> impl DoubleEndedIterator<Item = &str> {
492 // A slice rather than an array: only the slice form searches backwards on the pinned minimum
493 // supported Rust version.
494 const SEPARATORS: &[char] = &['/', '\\'];
495 path.split(SEPARATORS).filter(|s| !s.is_empty())
496}
497
498fn file_name(path: &str) -> &str {
499 components(path).next_back().unwrap_or("")
500}
501
502fn file_stem(path: &str) -> &str {
503 let name = file_name(path);
504 name.strip_suffix(".exe").unwrap_or(name)
505}
506
507fn parent_of(path: &str) -> &str {
508 match path.rfind(['/', '\\']) {
509 Some(at) => path.get(..at).unwrap_or(""),
510 None => "",
511 }
512}
513
514/// The value of `--name value` or `--name=value`, whichever form was used.
515fn value_of<'a>(args: &'a [String], name: &str) -> Option<&'a str> {
516 values_of_borrowed(args, name).first().copied()
517}
518
519fn values_of(args: &[String], name: &str) -> Vec<String> {
520 values_of_borrowed(args, name)
521 .into_iter()
522 .map(str::to_owned)
523 .collect()
524}
525
526fn values_of_borrowed<'a>(args: &'a [String], name: &str) -> Vec<&'a str> {
527 let mut out = Vec::new();
528 let mut expecting = false;
529 for arg in args {
530 if expecting {
531 out.push(arg.as_str());
532 expecting = false;
533 continue;
534 }
535 if arg == name {
536 expecting = true;
537 } else if let Some(rest) = arg.strip_prefix(name) {
538 if let Some(value) = rest.strip_prefix('=') {
539 out.push(value);
540 } else if name.len() == 2 && !rest.is_empty() {
541 // Short options such as `-Cmetadata=…` may be written without a separator.
542 out.push(rest);
543 }
544 }
545 }
546 out
547}
548
549fn truncate(line: &str) -> String {
550 const LIMIT: usize = 120;
551 match line.char_indices().nth(LIMIT) {
552 Some((at, _)) => match line.get(..at) {
553 Some(head) => format!("{head}…"),
554 None => line.to_owned(),
555 },
556 None => line.to_owned(),
557 }
558}