1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
//! Everything that can go wrong reading a build's output.
use core::fmt;
use critpath_core::GraphError;
/// Enough of a unit's identity to name it in an error message.
///
/// A unit that could not be matched has to be described from whichever side saw it, so the fields
/// that side does not know are empty rather than invented.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
#[non_exhaustive]
pub struct UnitDescription {
/// Package name, where it is known.
pub package: String,
/// Package version, where it is known.
pub version: String,
/// Target within the package: `lib`, a binary name, or a build-script phase.
pub target: String,
/// Where in its input the unit was seen, counted from one, for locating it by eye.
pub position: usize,
}
impl fmt::Display for UnitDescription {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let package = if self.package.is_empty() {
"<unknown package>"
} else {
&self.package
};
write!(f, "{package}")?;
if !self.version.is_empty() {
write!(f, " {}", self.version)?;
}
if !self.target.is_empty() {
write!(f, " ({})", self.target)?;
}
write!(f, " [#{}]", self.position)
}
}
/// A build's output that could not be turned into a graph, and why.
///
/// Every variant's message states what to do next, because the usual cause is that the build the
/// output came from was not the kind of build the analysis needs.
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub enum ParseError {
/// The input holds NUL characters, so it is not the UTF-8 text Cargo wrote.
NotUtf8 {
/// What was being read, for the message: `build log` or `timing report`.
what: &'static str,
/// How many NUL characters were found.
nuls: usize,
},
/// The verbose log contained no compiler invocations at all.
NoInvocations,
/// A `Running` line could not be split into arguments because a quote was left open.
UnbalancedQuoting {
/// The offending line, truncated.
line: String,
},
/// The timing report contained no `UNIT_DATA` array.
NoUnitData,
/// A JavaScript array literal in the timing report was not valid JSON.
MalformedArray {
/// The name of the assignment, such as `UNIT_DATA`.
name: String,
/// What `serde_json` said about it.
detail: String,
},
/// An array literal in the timing report was cut off before its closing bracket.
TruncatedArray {
/// The name of the assignment, such as `UNIT_DATA`.
name: String,
},
/// A `UNIT_DATA` entry was missing a field, or the field had the wrong type.
BadUnitField {
/// Which entry, counted from zero as the report numbers them.
entry: usize,
/// The field that was wrong.
field: &'static str,
/// What was expected of it.
expected: &'static str,
},
/// The timing report's summary table was absent or unreadable.
NoSummaryTable,
/// The timing report's summary table lacked a row the analysis needs.
MissingSummaryRow {
/// The row's label, as Cargo writes it.
row: &'static str,
},
/// A summary row was present but did not hold the expected kind of value.
BadSummaryRow {
/// The row's label, as Cargo writes it.
row: &'static str,
/// What the row actually contained.
value: String,
/// What was expected of it.
expected: &'static str,
},
/// The build reused cached units, so most of its weights are zero.
FreshUnits {
/// How many units were reused.
fresh: usize,
/// How many units the build had in total.
total: usize,
},
/// The build compiled nothing.
EmptyBuild,
/// A duration in the timing report is not a duration.
DurationOutOfRange {
/// Which entry, counted from zero.
entry: usize,
/// The value that could not be used.
seconds: f64,
},
/// The two inputs describe different sets of units.
UnmatchedUnits {
/// Units the verbose log has and the timing report does not.
in_log: Vec<UnitDescription>,
/// Units the timing report has and the verbose log does not.
in_report: Vec<UnitDescription>,
/// Whether `cargo metadata` output was supplied.
had_metadata: bool,
},
/// A `--extern` names an artifact no invocation in this log produced.
UnresolvedDependency {
/// The unit that named it, boxed so that a failure path does not widen every `Result` in
/// the crate.
consumer: Box<UnitDescription>,
/// The `--extern` name.
dependency: String,
/// The artifact path's producer hash, where there was one.
producer: String,
},
/// `cargo metadata` output could not be read.
Metadata {
/// What was wrong with it.
detail: String,
},
/// The assembled graph was rejected by the core.
Graph(GraphError),
}
impl fmt::Display for ParseError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::NotUtf8 { what, nuls } => write!(
f,
"the {what} holds {nuls} NUL characters, so it is not the UTF-8 text Cargo wrote; \
a redirection under PowerShell writes UTF-16. Capture it with \
`cargo build --timings -v --offline 2>&1 | Out-File -Encoding utf8 build.log`, \
or from a shell that redirects as UTF-8"
),
Self::NoInvocations => write!(
f,
"the build log contains no compiler invocations; \
it was captured without -v, or every unit was already up to date. \
Run `cargo clean` and then \
`cargo build --timings -v --offline 2>build.log`"
),
Self::UnbalancedQuoting { line } => write!(
f,
"a `Running` line in the build log has an unclosed quote and cannot be split into \
arguments: {line}. \
The log is probably truncated; capture it again, redirecting stderr to a file \
rather than copying it out of a terminal"
),
Self::NoUnitData => write!(
f,
"the timing report contains no `UNIT_DATA` array, so it holds no per-unit times. \
Check that the file is the `cargo-timing.html` Cargo wrote and not the \
`cargo-timing-<date>.html` copy of an older run, and that the build used --timings"
),
Self::MalformedArray { name, detail } => write!(
f,
"the `{name}` array in the timing report is not valid JSON ({detail}); \
this Cargo version writes a shape the parser does not know. \
Report the Cargo version, and in the meantime the analysis cannot use this report"
),
Self::TruncatedArray { name } => write!(
f,
"the `{name}` array in the timing report is cut off before its closing bracket, \
so the file is incomplete; \
the build was probably interrupted, so run it again to completion"
),
Self::BadUnitField {
entry,
field,
expected,
} => write!(
f,
"entry {entry} of `UNIT_DATA` has no usable `{field}` (expected {expected}); \
this Cargo version writes a shape the parser does not know, \
so report the Cargo version"
),
Self::NoSummaryTable => write!(
f,
"the timing report has no summary table, so the build's unit counts and job limit \
cannot be read; \
check that the file is a complete `cargo-timing.html`"
),
Self::MissingSummaryRow { row } => write!(
f,
"the timing report's summary table has no `{row}` row, \
so the analysis cannot tell whether the build was a clean one; \
this Cargo version writes a shape the parser does not know, \
so report the Cargo version"
),
Self::BadSummaryRow {
row,
value,
expected,
} => write!(
f,
"the timing report's `{row}` row holds {value:?}, which is not {expected}; \
this Cargo version writes a shape the parser does not know, \
so report the Cargo version"
),
Self::FreshUnits { fresh, total } => write!(
f,
"{fresh} of this build's {total} units were reused from the cache, so their \
recorded durations are zero and any critical path computed from them would be \
meaningless. \
Run `cargo clean` first, then \
`cargo build --timings -v --offline 2>build.log`"
),
Self::EmptyBuild => write!(
f,
"the build compiled nothing, so there is no graph to analyse; \
run `cargo clean` and build again"
),
Self::DurationOutOfRange { entry, seconds } => write!(
f,
"entry {entry} of `UNIT_DATA` reports a duration of {seconds} seconds, which is \
not a duration this analysis can use; \
the report is corrupt, so run the build again"
),
Self::UnmatchedUnits {
in_log,
in_report,
had_metadata,
} => {
write!(
f,
"the build log and the timing report describe different sets of units, \
so a graph built from them would silently omit work"
)?;
if !in_log.is_empty() {
write!(f, "; only in the build log: ")?;
write_list(f, in_log)?;
}
if !in_report.is_empty() {
write!(f, "; only in the timing report: ")?;
write_list(f, in_report)?;
}
write!(
f,
". Both must come from the same build, so capture them together with "
)?;
write!(f, "`cargo build --timings -v --offline 2>build.log`")?;
if *had_metadata {
write!(
f,
". The `cargo metadata` output supplied did not cover these units, so \
check that it came from the same workspace"
)
} else {
write!(
f,
". Supplying `cargo metadata --format-version 1` output as well would let \
a workspace-local package be attributed to its manifest exactly instead \
of by its directory name"
)
}
}
Self::UnresolvedDependency {
consumer,
dependency,
producer,
} => write!(
f,
"unit {consumer} depends on `{dependency}` through artifact {producer}, which no \
invocation in this log produced, so an edge would be missing from the graph and \
the critical path would be understated. \
That happens when part of the build was already up to date: \
run `cargo clean` and build again"
),
Self::Metadata { detail } => write!(
f,
"the `cargo metadata` output could not be read ({detail}); \
produce it with `cargo metadata --format-version 1`, \
or omit it and local packages will be attributed by directory name instead"
),
Self::Graph(inner) => write!(
f,
"the graph assembled from this build was rejected: {inner}. \
This is a defect in the adapter rather than in the build, so please report it \
with the Cargo version"
),
}
}
}
fn write_list(f: &mut fmt::Formatter<'_>, units: &[UnitDescription]) -> fmt::Result {
const SHOWN: usize = 8;
for (i, unit) in units.iter().take(SHOWN).enumerate() {
if i > 0 {
write!(f, ", ")?;
}
write!(f, "{unit}")?;
}
if units.len() > SHOWN {
write!(f, ", and {} more", units.len().saturating_sub(SHOWN))?;
}
Ok(())
}
impl std::error::Error for ParseError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Graph(inner) => Some(inner),
_ => None,
}
}
}
impl From<GraphError> for ParseError {
fn from(inner: GraphError) -> Self {
Self::Graph(inner)
}
}
/// Refuses text that holds NUL characters.
///
/// Cargo's output is UTF-8 and never contains a NUL. UTF-16LE without a byte-order mark decodes as
/// valid UTF-8 in which every second character is one, so this is what tells a mis-encoded capture
/// apart from an empty one. A stray NUL is not tolerated either: there is no reading under which
/// Cargo would have written one.
pub(crate) fn reject_wide_text(text: &str, what: &'static str) -> Result<(), ParseError> {
let nuls = text.bytes().filter(|b| *b == 0).count();
if nuls > 0 {
return Err(ParseError::NotUtf8 { what, nuls });
}
Ok(())
}