Skip to content

Commit dcc3e6e

Browse files
mluggmlugg
committed
build system: replace fuzzing UI with build UI, add time report
This commit replaces the "fuzzer" UI, previously accessed with the `--fuzz` and `--port` flags, with a more interesting web UI which allows more interactions with the Zig build system. Most notably, it allows accessing the data emitted by a new "time report" system, which allows users to see which parts of Zig programs take the longest to compile. The option to expose the web UI is `--webui`. By default, it will listen on `[::1]` on a random port, but any IPv6 or IPv4 address can be specified with e.g. `--webui=[::1]:8000` or `--webui=127.0.0.1:8000`. The options `--fuzz` and `--time-report` both imply `--webui` if not given. Currently, `--webui` is incompatible with `--watch`; specifying both will cause `zig build` to exit with a fatal error. When the web UI is enabled, the build runner spawns the web server as soon as the configure phase completes. The frontend code consists of one HTML file, one JavaScript file, two CSS files, and a few Zig source files which are built into a WASM blob on-demand -- this is all very similar to the old fuzzer UI. Also inherited from the fuzzer UI is that the build system communicates with web clients over a WebSocket connection. When the build finishes, if `--webui` was passed (i.e. if the web server is running), the build runner does not terminate; it continues running to serve web requests, allowing interactive control of the build system. In the web interface is an overall "status" indicating whether a build is currently running, and also a list of all steps in this build. There are visual indicators (colors and spinners) for in-progress, succeeded, and failed steps. There is a "Rebuild" button which will cause the build system to reset the state of every step (note that this does not affect caching) and evaluate the step graph again. If `--time-report` is passed to `zig build`, a new section of the interface becomes visible, which associates every build step with a "time report". For most steps, this is just a simple "time taken" value. However, for `Compile` steps, the compiler communicates with the build system to provide it with much more interesting information: time taken for various pipeline phases, with a per-declaration and per-file breakdown, sorted by slowest declarations/files first. This feature is still in its early stages: the data can be a little tricky to understand, and there is no way to, for instance, sort by different properties, or filter to certain files. However, it has already given us some interesting statistics, and can be useful for spotting, for instance, particularly complex and slow compile-time logic. Additionally, if a compilation uses LLVM, its time report includes the "LLVM pass timing" information, which was previously accessible with the (now removed) `-ftime-report` compiler flag. To make time reports more useful, ZIR and compilation caches are ignored by the Zig compiler when they are enabled -- in other words, `Compile` steps *always* run, even if their result should be cached. This means that the flag can be used to analyze a project's compile time without having to repeatedly clear cache directory, for instance. However, when using `-fincremental`, updates other than the first will only show you the statistics for what changed on that particular update. Notably, this gives us a fairly nice way to see exactly which declarations were re-analyzed by an incremental update. If `--fuzz` is passed to `zig build`, another section of the web interface becomes visible, this time exposing the fuzzer. This is quite similar to the fuzzer UI this commit replaces, with only a few cosmetic tweaks. The interface is closer than before to supporting multiple fuzz steps at a time (in line with the overall strategy for this build UI, the goal will be for all of the fuzz steps to be accessible in the same interface), but still doesn't actually support it. The fuzzer UI looks quite different under the hood: as a result, various bugs are fixed, although other bugs remain. For instance, viewing the source code of any file other than the root of the main module is completely broken (as on master) due to some bogus file-to-module assignment logic in the fuzzer UI. Implementation notes: * The `lib/build-web/` directory holds the client side of the web UI. * The general server logic is in `std.Build.WebServer`. * Fuzzing-specific logic is in `std.Build.Fuzz`. * `std.Build.abi` is the new home of `std.Build.Fuzz.abi`, since it now relates to the build system web UI in general. * The build runner now has an **actual** general-purpose allocator, because thanks to `--watch` and `--webui`, the process can be arbitrarily long-lived. The gpa is `std.heap.DebugAllocator`, but the arena remains backed by `std.heap.page_allocator` for efficiency. I fixed several crashes caused by conflation of `gpa` and `arena` in the build runner and `std.Build`, but there may still be some I have missed. * The I/O logic in `std.Build.WebServer` is pretty gnarly; there are a *lot* of threads involved. I anticipate this situation improving significantly once the `std.Io` interface (with concurrency support) is introduced.
1 parent a00edbd commit dcc3e6e

38 files changed

+3751
-1787
lines changed

‎lib/fuzzer/web/main.zig renamed to ‎lib/build-web/fuzz.zig

Lines changed: 214 additions & 292 deletions
Large diffs are not rendered by default.

‎lib/build-web/index.html

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
<!doctype html>
2+
3+
<meta charset="utf-8">
4+
<title>Zig Build System</title>
5+
<link rel="stylesheet" href="style.css">
6+
<!-- Highly compressed 32x32 Zig logo -->
7+
<link rel="icon" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAABSklEQVRYw8WWXbLDIAiFP5xuURYpi+Q+VDvJTYxaY8pLJ52EA5zDj/AD8wRABCw8DeyJBDiAKMiDGaecNYCKYgCvh4EBjPgGh0UVqAB/MEU3D57efDRMiRhWddprCljRAECPCE0Uw4iz4Jn3tP2zFYAB6on4/8NBM1Es+9kl0aKgaMRnwHPpT5MIDb6YzLzp57wNIyIC7iCCdijeL3gv78jZe6cVENn/drRbXbxl4lXSmB3FtbY0iNrjIEwMm6u2VFFjWQCN0qtov6+wANxG/IV7eR8DHw6gzft4NuEXvA8HcDfv31SgyvsMeDUA90/WTd47bsCdv8PUrWzDyw02uIYv13ktgOVr+IqCouila7gWgNYuly/BfVSEdsP5Vdqyiz7pPC40C+p2e21bL5/dByGtAD6eZPuzeznwjoIN748BfyqwmVDyJHCxPwLSkjUkraEXAAAAAElFTkSuQmCC">
8+
9+
<!-- Templates, to be cloned into shadow DOMs by JavaScript -->
10+
11+
<template id="timeReportEntryTemplate">
12+
<link rel="stylesheet" href="style.css">
13+
<link rel="stylesheet" href="time_report.css">
14+
<details>
15+
<summary><slot name="step-name"></slot></summary>
16+
<div id="genericReport">
17+
<div class="stats">
18+
Time: <slot name="stat-total-time"></slot><br>
19+
</div>
20+
</div>
21+
<div id="compileReport">
22+
<div class="stats">
23+
Files Discovered: <slot name="stat-reachable-files"></slot><br>
24+
Files Analyzed: <slot name="stat-imported-files"></slot><br>
25+
Generic Instances Analyzed: <slot name="stat-generic-instances"></slot><br>
26+
Inline Calls Analyzed: <slot name="stat-inline-calls"></slot><br>
27+
Compilation Time: <slot name="stat-compilation-time"></slot><br>
28+
</div>
29+
<table class="time-stats">
30+
<thead>
31+
<tr>
32+
<th scope="col">Pipeline Component</th>
33+
<th scope="col" class="tooltip">CPU Time
34+
<span class="tooltip-content">Sum across all threads of the time spent in this pipeline component</span>
35+
</th>
36+
<th scope="col" class="tooltip">Real Time
37+
<span class="tooltip-content">Wall-clock time elapsed between the start and end of this compilation phase</span>
38+
</th>
39+
<th scope="col">Compilation Phase</th>
40+
</tr>
41+
</thead>
42+
<tbody>
43+
<tr>
44+
<th scope="row" class="tooltip">Parsing
45+
<span class="tooltip-content"><code>tokenize</code> converts a file of Zig source code into a sequence of tokens, which are then processed by <code>Parse</code> into an Abstract Syntax Tree (AST).</span>
46+
</th>
47+
<td><slot name="cpu-time-parse"></slot></td>
48+
<td rowspan="2"><slot name="real-time-files"></slot></td>
49+
<th scope="row" rowspan="2" class="tooltip">File Lower
50+
<span class="tooltip-content">Tokenization, parsing, and lowering of Zig source files to a high-level IR.<br><br>Starting from module roots, every file theoretically accessible through a chain of <code>@import</code> calls is processed. Individual source files are processed serially, but different files are processed in parallel by a thread pool.<br><br>The results of this phase of compilation are cached on disk per source file, meaning the time spent here is typically only relevant to "clean" builds.</span>
51+
</th>
52+
</tr>
53+
<tr>
54+
<th scope="row" class="tooltip">AST Lowering
55+
<span class="tooltip-content"><code>AstGen</code> converts a file's AST into a high-level SSA IR named Zig Intermediate Representation (ZIR). The resulting ZIR code is cached on disk to avoid, for instance, re-lowering all source files in the Zig standard library each time the compiler is invoked.</span>
56+
</th>
57+
<td><slot name="cpu-time-astgen"></slot></td>
58+
</tr>
59+
<tr>
60+
<th scope="row" class="tooltip">Semantic Analysis
61+
<span class="tooltip-content"><code>Sema</code> interprets ZIR to perform type checking, compile-time code execution, and type resolution, collectively termed "semantic analysis". When a runtime function body is analyzed, it emits Analyzed Intermediate Representation (AIR) code to be sent to the next pipeline component. Semantic analysis is currently entirely single-threaded.</span>
62+
</th>
63+
<td><slot name="cpu-time-sema"></slot></td>
64+
<td rowspan="3"><slot name="real-time-decls"></slot></td>
65+
<th scope="row" rowspan="3" class="tooltip">Declaration Lower
66+
<span class="tooltip-content">Semantic analysis, code generation, and linking, at the granularity of individual declarations (as opposed to whole source files).<br><br>These components are run in parallel with one another. Semantic analysis is almost always the bottleneck, as it is complex and currently can only run single-threaded.<br><br>This phase completes when a work queue empties, but semantic analysis may add work by one declaration referencing another.<br><br>This is the main phase of compilation, typically taking significantly longer than File Lower (even in a clean build).</span>
67+
</th>
68+
</tr>
69+
<tr>
70+
<th scope="row" class="tooltip">Code Generation
71+
<span class="tooltip-content"><code>CodeGen</code> converts AIR from <code>Sema</code> into machine instructions in the form of Machine Intermediate Representation (MIR). This work is usually highly parallel, since in most cases, arbitrarily many functions can be run through <code>CodeGen</code> simultaneously.</span>
72+
</th>
73+
<td><slot name="cpu-time-codegen"></slot></td>
74+
</tr>
75+
<tr>
76+
<th scope="row" class="tooltip">Linking
77+
<span class="tooltip-content"><code>link</code> converts MIR from <code>CodeGen</code>, as well as global constants and variables from <code>Sema</code>, and places them in the output binary. MIR is converted to a finished sequence of real instruction bytes.<br><br>When using the LLVM backend, most of this work is instead deferred to the "LLVM Emit" phase.</span>
78+
</th>
79+
<td><slot name="cpu-time-link"></slot></td>
80+
</tr>
81+
<tr class="llvm-only">
82+
<th class="empty-cell"></th>
83+
<td class="empty-cell"></td>
84+
<td><slot name="real-time-llvm-emit"></slot></td>
85+
<th scope="row" class="tooltip">LLVM Emit
86+
<span class="tooltip-content"><b>Only applicable when using the LLVM backend.</b><br><br>Conversion of generated LLVM bitcode to an object file, including any optimization passes.<br><br>When using LLVM, this phase of compilation is typically the slowest by a significant margin. Unfortunately, the Zig compiler implementation has essentially no control over it.</span>
87+
</th>
88+
</tr>
89+
<tr>
90+
<th class="empty-cell"></th>
91+
<td class="empty-cell"></td>
92+
<td><slot name="real-time-link-flush"></slot></td>
93+
<th scope="row" class="tooltip">Linker Flush
94+
<span class="tooltip-content">Finalizing the emitted binary, and ensuring it is fully written to disk.<br><br>When using LLD, this phase represents the entire linker invocation. Otherwise, the amount of work performed here is dependent on details of Zig's linker implementation for the particular output format, but typically aims to be fairly minimal.</span>
95+
</th>
96+
</tr>
97+
</tbody>
98+
</table>
99+
<details class="section">
100+
<summary>Files</summary>
101+
<table class="time-stats">
102+
<thead>
103+
<tr>
104+
<th scope="col">File</th>
105+
<th scope="col">Semantic Analysis</th>
106+
<th scope="col">Code Generation</th>
107+
<th scope="col">Linking</th>
108+
</tr>
109+
</thead>
110+
<!-- HTML does not allow placing a 'slot' inside of a 'tbody' for backwards-compatibility
111+
reasons, so we unfortunately must template on the `id` here. -->
112+
<tbody id="fileTableBody"></tbody>
113+
</table>
114+
</details>
115+
<details class="section">
116+
<summary>Declarations</summary>
117+
<table class="time-stats">
118+
<thead>
119+
<tr>
120+
<th scope="col">File</th>
121+
<th scope="col">Declaration</th>
122+
<th scope="col" class="tooltip">Analysis Count
123+
<span class="tooltip-content">The number of times the compiler analyzed some part of this declaration. If this is a function, <code>inline</code> and <code>comptime</code> calls to it are <i>not</i> included here. Typically, this value is approximately equal to the number of instances of a generic declaration.</span>
124+
</th>
125+
<th scope="col">Semantic Analysis</th>
126+
<th scope="col">Code Generation</th>
127+
<th scope="col">Linking</th>
128+
</tr>
129+
</thead>
130+
<!-- HTML does not allow placing a 'slot' inside of a 'tbody' for backwards-compatibility
131+
reasons, so we unfortunately must template on the `id` here. -->
132+
<tbody id="declTableBody"></tbody>
133+
</table>
134+
</details>
135+
<details class="section llvm-only">
136+
<summary>LLVM Pass Timings</summary>
137+
<div><slot name="llvm-pass-timings"></slot></div>
138+
</details>
139+
</div>
140+
</details>
141+
</template>
142+
143+
<template id="fuzzEntryTemplate">
144+
<link rel="stylesheet" href="style.css">
145+
<ul>
146+
<li>Total Runs: <slot name="stat-total-runs"></slot></li>
147+
<li>Unique Runs: <slot name="stat-unique-runs"></slot></li>
148+
<li>Speed: <slot name="stat-speed"></slot> runs/sec</li>
149+
<li>Coverage: <slot name="stat-coverage"></slot></li>
150+
</ul>
151+
<!-- I have observed issues in Firefox clicking frequently-updating slotted links, so the entry
152+
point list is handled separately since it rarely changes. -->
153+
<ul id="entryPointList" class="no-marker"></ul>
154+
<div id="source" class="hidden">
155+
<h2>Source Code</h2>
156+
<pre><code id="sourceText"></code></pre>
157+
</div>
158+
</template>
159+
160+
<!-- The actual body: fairly minimal, content populated by JavaScript -->
161+
162+
<p id="connectionStatus">Loading JavaScript...</p>
163+
<p class="hidden" id="firefoxWebSocketBullshitExplainer">
164+
If you are using Firefox and <code>zig build --listen</code> is definitely running, you may be experiencing an unreasonably aggressive exponential
165+
backoff for WebSocket connection attempts, which is enabled by default and can block connection attempts for up to a minute. To disable this limit,
166+
open <code>about:config</code> and set the <code>network.websocket.delay-failed-reconnects</code> option to <code>false</code>.
167+
</p>
168+
<main class="hidden">
169+
<h1>Zig Build System</h1>
170+
171+
<p><span id="summaryStatus"></span> | <span id="summaryStepCount"></span> steps</p>
172+
<button class="big-btn" id="buttonRebuild" disabled>Rebuild</button>
173+
174+
<ul class="no-marker" id="stepList"></ul>
175+
176+
<hr>
177+
178+
<div id="timeReport" class="hidden">
179+
<h1>Time Report</h1>
180+
<div id="timeReportList"></div>
181+
<hr>
182+
</div>
183+
184+
<div id="fuzz" class="hidden">
185+
<h1>Fuzzer</h1>
186+
<p id="fuzzStatus"></p>
187+
<div id="fuzzEntries"></div>
188+
<hr>
189+
</div>
190+
191+
<h1>Help</h1>
192+
<p>This is the Zig Build System web interface. It allows live interaction with the build system.</p>
193+
<p>The following <code>zig build</code> flags can expose extra features of this interface:</p>
194+
<ul>
195+
<li><code>--time-report</code>: collect and show statistics about the time taken to evaluate a build graph</li>
196+
<li><code>--fuzz</code>: enable the fuzzer for any Zig test binaries in the build graph (experimental)</li>
197+
</ul>
198+
</main>
199+
200+
<!-- JavaScript at the very end -->
201+
202+
<script src="main.js"></script>

0 commit comments

Comments
 (0)