Skip to main content

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}