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
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
|
//! sketchbook: a host that hot-reloads sketches, and the library they use.
//!
//! Apps use it from their own build.zig:
//!
//! const sketchbook = @import("sketchbook");
//!
//! const sb = sketchbook.init(b, .{ .target = target, .optimize = optimize });
//! const app = sb.app(.{ .name = "demo", .root_source_file = b.path("src/main.zig") });
//! _ = app.addSteps(.{}); // run, lib, probe, e2e, test, install;
//! // web and serve with `.web = .{}`
//!
//! or pick the pieces: `app.addLibrary()`, `app.addExecutable()`,
//! `app.addWeb(...)`, `app.addRun(...)`, `app.addScript(...)`,
//! `app.addProbe(...)`, `app.addTest(...)`. GPU shaders are GLSL, built by
//! `sb.addShaders(...)` into SPIR-V for native hosts and WGSL for the web;
//! `sb.addGlslLayouts(...)` and `sb.addGlslc(...)` are its pieces. Each
//! returns the ordinary `std.Build` objects, so anything can be extended or
//! rewired.
//!
//! Tools, found on PATH when a step needs them: `glslc` (shaderc or the
//! Vulkan SDK) for any shader, `naga` (`cargo install naga-cli`) only for
//! the web build of a sketch with shaders, and `miniserve` and `openssl`
//! only for `serve`.
const std = @import("std");
const Build = std.Build;
const translate_c = @import("translate_c");
pub fn build(b: *Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
// Target-free: they compile for whatever imports them, native or wasm.
const abi = b.addModule("abi", .{ .root_source_file = b.path("src/abi.zig") });
const sketch = b.addModule("sketch", .{
.root_source_file = b.path("src/sketch/root.zig"),
.imports = &.{.{ .name = "abi", .module = abi }},
});
const c = cModule(b, target, optimize);
const host = b.addModule("host", .{
.root_source_file = b.path("src/host/root.zig"),
.target = target,
.optimize = optimize,
.imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "c", .module = c } },
});
const host_exe = b.addExecutable(.{
.name = "sketchbook",
.root_module = b.createModule(.{
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
.imports = &.{.{ .name = "host", .module = host }},
}),
});
b.installArtifact(host_exe);
const probe = b.addExecutable(.{
.name = "sketchbook-probe",
.root_module = b.createModule(.{
.root_source_file = b.path("src/host/probe.zig"),
.target = target,
.optimize = optimize,
.imports = &.{.{ .name = "abi", .module = abi }},
}),
});
b.installArtifact(probe);
var sb: Sketchbook = .{ .b = b, .target = target, .optimize = optimize, .modules = .{ .abi = abi, .sketch = sketch, .host = host, .vector = undefined, .scope = undefined }, .host_exe = host_exe, .probe_exe = probe, .web = b.path("web"), .glsl = b.path("src/glsl.zig"), .shared = .create(b) };
// Vector graphics: built with the same shader step apps use. Both forms
// of its shaders are exported, so apps' web builds can swap them too.
const vector_layouts = b.createModule(.{ .root_source_file = b.path("src/vector/layouts.zig") });
const vector_shaders = sb.addShaders(.{
.layouts = .{ .module = vector_layouts, .types = &.{ "Vertex", "Viewport", "Paint" } },
.sources = &.{ b.path("src/vector/shaders/path.vert"), b.path("src/vector/shaders/stencil.frag"), b.path("src/vector/shaders/cover.frag") },
});
b.modules.put(b.graph.arena, "vector_shaders", vector_shaders.module) catch @panic("OOM");
b.modules.put(b.graph.arena, "vector_shaders_web", vector_shaders.web) catch @panic("OOM");
const vector_imports: []const Build.Module.Import = &.{
.{ .name = "abi", .module = abi },
.{ .name = "vector_layouts", .module = vector_layouts },
.{ .name = "vector_shaders", .module = vector_shaders.module },
};
sb.modules.vector = b.addModule("vector", .{ .root_source_file = b.path("src/vector/root.zig"), .imports = vector_imports });
// Sound scopes: waveform, spectrogram, spectrum and oscilloscope of a
// stream of samples, analysed and drawn on the GPU.
const scope_layouts = b.createModule(.{ .root_source_file = b.path("src/scope/layouts.zig") });
const scope_shaders = sb.addShaders(.{
.layouts = .{ .module = scope_layouts, .types = &.{ "SpectrumParams", "WaveParams", "WaveView", "SpectrumView", "SpectrogramParams", "SpectrogramView" } },
.sources = &.{
b.path("src/scope/shaders/view.vert"),
b.path("src/scope/shaders/waveform.comp"),
b.path("src/scope/shaders/waveform.frag"),
b.path("src/scope/shaders/spectrogram.comp"),
b.path("src/scope/shaders/spectrogram.frag"),
b.path("src/scope/shaders/spectrum.comp"),
b.path("src/scope/shaders/spectrum.frag"),
},
});
b.modules.put(b.graph.arena, "scope_shaders", scope_shaders.module) catch @panic("OOM");
b.modules.put(b.graph.arena, "scope_shaders_web", scope_shaders.web) catch @panic("OOM");
const scope_imports: []const Build.Module.Import = &.{
.{ .name = "sketch", .module = sketch },
.{ .name = "scope_layouts", .module = scope_layouts },
.{ .name = "scope_shaders", .module = scope_shaders.module },
};
sb.modules.scope = b.addModule("scope", .{ .root_source_file = b.path("src/scope/root.zig"), .imports = scope_imports });
const test_step = b.step("test", "Run unit tests and the reload end-to-end test");
for ([_]*Build.Module{
b.createModule(.{ .root_source_file = b.path("src/vector/root.zig"), .target = target, .optimize = optimize, .imports = vector_imports }),
b.createModule(.{ .root_source_file = b.path("src/scope/root.zig"), .target = target, .optimize = optimize, .imports = scope_imports }),
b.createModule(.{ .root_source_file = b.path("src/glsl.zig"), .target = target, .optimize = optimize }),
b.createModule(.{ .root_source_file = b.path("src/abi.zig"), .target = target, .optimize = optimize }),
b.createModule(.{ .root_source_file = b.path("src/sketch/root.zig"), .target = target, .optimize = optimize, .imports = &.{.{ .name = "abi", .module = abi }} }),
b.createModule(.{ .root_source_file = b.path("src/host/root.zig"), .target = target, .optimize = optimize, .imports = &.{ .{ .name = "abi", .module = abi }, .{ .name = "c", .module = c } } }),
}) |module| test_step.dependOn(&b.addRunArtifact(b.addTest(.{ .root_module = module })).step);
// A sketch reloaded mid-run with a changed layout: state carried over by
// field name, through the real dlopen path and the headless host.
const v1 = sb.app(.{ .name = "counter", .root_source_file = b.path("test/counter_v1.zig") }).addLibrary();
const v2 = sb.app(.{ .name = "counter", .root_source_file = b.path("test/counter_v2.zig") }).addLibrary();
// The README's example, so the documentation always compiles.
test_step.dependOn(&sb.app(.{ .name = "readme", .root_source_file = b.path("test/readme.zig") }).addLibrary().step);
const reload = b.addRunArtifact(host_exe);
reload.addArgs(&.{ "--headless", "--fresh", "--script" });
reload.addFileArg(b.path("test/reload.script"));
reload.addArg("--state");
_ = reload.addOutputFileArg("counter.state");
reload.addArg("--define");
reload.addPrefixedArtifactArg("v2=", v2);
reload.addArtifactArg(v1);
reload.expectExitCode(0);
test_step.dependOn(&reload.step);
}
fn cModule(b: *Build, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode) *Build.Module {
const sdl_dep = b.dependency("sdl", .{ .target = target, .optimize = optimize });
const sdl = sdl_dep.artifact("SDL3");
if (target.result.os.tag == .linux) fixSdlThreadCleanup(b, sdl.root_module, sdl_dep.path("src"));
const translator: translate_c.Translator = .init(b.dependency("translate_c", .{}), .{
.c_source_file = b.addWriteFiles().add("c.h",
\\#define SDL_DISABLE_OLD_NAMES
\\#include <SDL3/SDL.h>
\\#include "codecs.h"
\\#include "text.h"
),
.target = target,
.optimize = optimize,
});
translator.linkLibrary(sdl);
translator.addIncludePath(b.path("vendor"));
translator.mod.addCSourceFile(.{ .file = b.path("vendor/codecs.c"), .flags = &.{"-fno-sanitize=undefined"} });
if (target.result.os.tag == .linux) {
translator.mod.addCSourceFile(.{ .file = b.path("vendor/text.c"), .flags = &.{"-std=c23"} });
translator.mod.linkSystemLibrary("pangocairo-1.0", .{ .use_pkg_config = .force });
translator.mod.linkSystemLibrary("pangoft2-1.0", .{ .use_pkg_config = .force });
}
return translator.mod;
}
/// SDL 3.4.14 gives its pthread TLS key no destructor, so threads SDL did not
/// create (PipeWire's) leave error storage behind when they exit. Compile the
/// original backend with an exit destructor; the pinned package is untouched.
fn fixSdlThreadCleanup(b: *Build, sdl: *Build.Module, source: Build.LazyPath) void {
var flags: ?[]const []const u8 = null;
for (sdl.link_objects.items) |object| {
if (object != .c_source_files) continue;
const group = object.c_source_files;
for (group.files, 0..) |file, i| {
if (!std.mem.eql(u8, file, "src/thread/pthread/SDL_systls.c")) continue;
const files = b.allocator.alloc([]const u8, group.files.len - 1) catch @panic("OOM");
@memcpy(files[0..i], group.files[0..i]);
@memcpy(files[i..], group.files[i + 1 ..]);
group.files = files;
flags = group.flags;
break;
}
}
std.debug.assert(flags != null);
const patched = b.addWriteFiles().add("SDL_systls_cleanup.c",
\\#include <pthread.h>
\\#include "SDL_internal.h"
\\#include "thread/SDL_systhread.h"
\\static void sketchbook_cleanup_tls(void *data) {
\\ /* pthread clears the key before calling us; SDL_CleanupTLS reads it. */
\\ if (SDL_SYS_SetTLSData(data)) SDL_CleanupTLS();
\\}
\\#define pthread_key_create(key, destructor) pthread_key_create(key, sketchbook_cleanup_tls)
\\#include "thread/pthread/SDL_systls.c"
);
sdl.addIncludePath(source);
sdl.addCSourceFile(.{ .file = patched, .flags = flags.? });
}
// ---------------------------------------------------------------------------
// Build API for apps
pub const Options = struct {
target: Build.ResolvedTarget,
optimize: std.builtin.OptimizeMode,
/// This package's name in the app's build.zig.zon.
dependency: []const u8 = "sketchbook",
};
pub fn init(b: *Build, options: Options) Sketchbook {
const dep = b.dependency(options.dependency, .{ .target = options.target, .optimize = options.optimize });
const shared: *Shared = .create(b);
for ([_][]const u8{ "vector_shaders", "scope_shaders" }) |name| {
shared.web_twins.put(b.graph.arena, dep.module(name), dep.module(b.fmt("{s}_web", .{name}))) catch @panic("OOM");
}
return .{
.b = b,
.target = options.target,
.optimize = options.optimize,
.modules = .{ .abi = dep.module("abi"), .sketch = dep.module("sketch"), .host = dep.module("host"), .vector = dep.module("vector"), .scope = dep.module("scope") },
.host_exe = dep.artifact("sketchbook"),
.probe_exe = dep.artifact("sketchbook-probe"),
.web = dep.path("web"),
.glsl = dep.path("src/glsl.zig"),
.shared = shared,
};
}
/// What every copy of a `Sketchbook` value shares.
const Shared = struct {
/// SPIR-V shader modules and their WGSL twins (see `addShaders`).
web_twins: std.AutoArrayHashMapUnmanaged(*Build.Module, *Build.Module) = .empty,
/// Lookups of external tools, made once, run when a step needs them.
glslc: ?Build.LazyPath = null,
naga: ?Build.LazyPath = null,
miniserve: ?Build.LazyPath = null,
openssl: ?Build.LazyPath = null,
/// A self-signed certificate and its key, for `addServe`.
certificate: ?Certificate = null,
const Certificate = struct { cert: Build.LazyPath, key: Build.LazyPath };
fn create(b: *Build) *Shared {
const shared = b.graph.arena.create(Shared) catch @panic("OOM");
shared.* = .{};
return shared;
}
};
pub const Sketchbook = struct {
b: *Build,
target: Build.ResolvedTarget,
optimize: std.builtin.OptimizeMode,
/// `vector`: SVG, cubic geometry, and CPU and GPU renderers. `scope`:
/// waveform, spectrogram, spectrum and oscilloscope views of a sound.
modules: struct { abi: *Build.Module, sketch: *Build.Module, host: *Build.Module, vector: *Build.Module, scope: *Build.Module },
/// The generic host: loads and hot-reloads a sketch library.
host_exe: *Build.Step.Compile,
/// Prints any sketch's state file.
probe_exe: *Build.Step.Compile,
/// `host.js` and the `index.html` template.
web: Build.LazyPath,
/// The GLSL declaration generator (see `addGlslLayouts`).
glsl: Build.LazyPath,
shared: *Shared,
pub const GlslLayouts = struct {
run: *Build.Step.Run,
/// `<Name>.glsl` for each type: pass it to `addGlslc` as an include.
dir: Build.LazyPath,
};
/// GLSL declarations generated from Zig types, so shaders and Zig share
/// one definition (see `glsl.zig`; std140 is checked as it runs).
/// `module` holds the types and must not depend on the shaders;
/// `types` are paths inside it, like "Vertex" or "gpu.Paint".
pub fn addGlslLayouts(sb: Sketchbook, options: struct { module: *Build.Module, types: []const []const u8 }) GlslLayouts {
const b = sb.b;
var paths: std.ArrayList(u8) = .empty;
for (options.types) |t| paths.print(b.allocator, "\"{s}\", ", .{t}) catch @panic("OOM");
const tool = b.addExecutable(.{
.name = "glsl-layouts",
.root_module = b.createModule(.{
.root_source_file = b.addWriteFiles().add("glsl_layouts.zig", b.fmt(
\\const std = @import("std");
\\pub fn main(init: std.process.Init) !void {{
\\ var args = init.minimal.args.iterate();
\\ _ = args.skip();
\\ var dir = try std.Io.Dir.cwd().createDirPathOpen(init.io, args.next().?, .{{}});
\\ defer dir.close(init.io);
\\ try @import("glsl").generate(@import("layouts"), &.{{ {s}}}, init.io, dir);
\\}}
, .{paths.items})),
.target = b.graph.host,
.imports = &.{
.{ .name = "glsl", .module = b.createModule(.{ .root_source_file = sb.glsl }) },
.{ .name = "layouts", .module = options.module },
},
}),
});
const run = b.addRunArtifact(tool);
return .{ .run = run, .dir = run.addOutputDirectoryArg("glsl") };
}
pub const Glslc = struct {
run: *Build.Step.Run,
spirv: Build.LazyPath,
};
/// One GLSL file compiled to SPIR-V by `glslc`.
pub fn addGlslc(sb: Sketchbook, options: struct {
source: Build.LazyPath,
include_dirs: []const Build.LazyPath = &.{},
/// Macros defined for the source, as `NAME` or `NAME=VALUE`.
defines: []const []const u8 = &.{},
target_env: []const u8 = "vulkan1.1",
optimize: bool = true,
}) Glslc {
const b = sb.b;
const name = std.fs.path.basename(options.source.getDisplayName());
const run = Build.Step.Run.create(b, b.fmt("glslc {s}", .{name}));
run.addFileArg(sb.glslc());
run.addArg(b.fmt("--target-env={s}", .{options.target_env}));
if (options.optimize) run.addArg("-O");
for (options.defines) |define| run.addArg(b.fmt("-D{s}", .{define}));
for (options.include_dirs) |dir| run.addPrefixedDirectoryArg("-I", dir);
// The files the source #includes, for the cache: editing one
// recompiles every shader that includes it.
run.addArgs(&.{ "-MD", "-MF" });
_ = run.addDepFileOutputArg(b.fmt("{s}.d", .{name}));
run.addArg("-o");
const spirv = run.addOutputFileArg(b.fmt("{s}.spv", .{name}));
run.addFileArg(options.source);
return .{ .run = run, .spirv = spirv };
}
pub const Shaders = struct {
/// SPIR-V, one `pub const <name>: []const u8` per shader, 4-byte
/// aligned as Vulkan reads it: the module to import.
module: *Build.Module,
/// The same declarations in WGSL, translated from the SPIR-V by
/// `naga`. The web build puts it in place of `module` wherever
/// `module` is imported (see `addWeb`), so sketches import one
/// module and never choose.
web: *Build.Module,
};
/// GLSL shaders for every host: compiled to SPIR-V, and for the web
/// compiled again with `SKETCHBOOK_WEB` defined and translated to WGSL,
/// which only the web build waits for. Each source is declared under its
/// file name with dots as underscores: `tuner.comp` is `tuner_comp`.
///
/// WGSL lacks a little GLSL has: no write-only storage buffers (declare
/// them `buffer`), and no `coherent` (WGSL's barriers make storage
/// writes visible to the workgroup anyway, so leave it out under
/// `#ifdef SKETCHBOOK_WEB`).
pub fn addShaders(sb: Sketchbook, options: struct {
sources: []const Build.LazyPath,
/// Uniform and vertex layouts generated from Zig types, which the
/// sources `#include` as `<Type>.glsl` (see `addGlslLayouts`).
layouts: ?struct { module: *Build.Module, types: []const []const u8 } = null,
/// More `#include` directories.
include_dirs: []const Build.LazyPath = &.{},
}) Shaders {
const b = sb.b;
const include_dirs = b.graph.arena.alloc(Build.LazyPath, options.include_dirs.len + 1) catch @panic("OOM");
@memcpy(include_dirs[0..options.include_dirs.len], options.include_dirs);
var dirs: []const Build.LazyPath = include_dirs[0..options.include_dirs.len];
if (options.layouts) |layouts| {
include_dirs[options.include_dirs.len] = sb.addGlslLayouts(.{ .module = layouts.module, .types = layouts.types }).dir;
dirs = include_dirs;
}
const native = b.addWriteFiles();
const web = b.addWriteFiles();
var native_source: std.ArrayList(u8) = .empty;
var web_source: std.ArrayList(u8) = .empty;
for (options.sources) |source| {
const file = std.fs.path.basename(source.getDisplayName());
const name = std.mem.replaceOwned(u8, b.graph.arena, file, ".", "_") catch @panic("OOM");
const spirv = sb.addGlslc(.{ .source = source, .include_dirs = dirs }).spirv;
_ = native.addCopyFile(spirv, b.fmt("{s}.spv", .{name}));
native_source.print(b.graph.arena, "const {s}_words align(4) = @embedFile(\"{s}.spv\").*;\npub const {s}: []const u8 = &{s}_words;\n", .{ name, name, name, name }) catch @panic("OOM");
const translate = Build.Step.Run.create(b, b.fmt("naga {s}", .{file}));
translate.addFileArg(sb.naga());
// SDL_GPU flips Vulkan's viewport, so the SPIR-V's clip space is
// already WebGPU's (y up): naga must not flip it again.
translate.addArg("--keep-coordinate-space");
translate.addFileArg(sb.addGlslc(.{ .source = source, .include_dirs = dirs, .defines = &.{"SKETCHBOOK_WEB"} }).spirv);
_ = web.addCopyFile(translate.addOutputFileArg(b.fmt("{s}.wgsl", .{name})), b.fmt("{s}.wgsl", .{name}));
web_source.print(b.graph.arena, "pub const {s}: []const u8 = @embedFile(\"{s}.wgsl\");\n", .{ name, name }) catch @panic("OOM");
}
const shaders: Shaders = .{
.module = b.createModule(.{ .root_source_file = native.add("spirv.zig", native_source.items) }),
.web = b.createModule(.{ .root_source_file = web.add("wgsl.zig", web_source.items) }),
};
sb.shared.web_twins.put(b.graph.arena, shaders.module, shaders.web) catch @panic("OOM");
return shaders;
}
/// `glslc`, from shaderc or the Vulkan SDK.
fn glslc(sb: Sketchbook) Build.LazyPath {
const sdk = if (sb.b.graph.environ_map.get("VULKAN_SDK")) |dir| sb.b.pathJoin(&.{ dir, "bin", "glslc" }) else "glslc";
return sb.program(&sb.shared.glslc, &.{ "glslc", sdk });
}
/// `naga`, from `cargo install naga-cli`: on PATH, or where cargo puts it.
fn naga(sb: Sketchbook) Build.LazyPath {
const env = &sb.b.graph.environ_map;
const cargo = if (env.get("CARGO_HOME")) |home| sb.b.pathJoin(&.{ home, "bin", "naga" }) else if (env.get("HOME")) |home| sb.b.pathJoin(&.{ home, ".cargo", "bin", "naga" }) else "naga";
return sb.program(&sb.shared.naga, &.{ "naga", cargo });
}
/// A tool found on PATH when a step needs it, looked up once.
fn program(sb: Sketchbook, slot: *?Build.LazyPath, names: []const []const u8) Build.LazyPath {
if (slot.* == null) slot.* = sb.b.findProgramLazy(.{ .names = names });
return slot.*.?;
}
/// A self-signed certificate for serving over https, made once by
/// `openssl` and kept in the cache: browsers ask to trust it once.
fn certificate(sb: Sketchbook) Shared.Certificate {
if (sb.shared.certificate == null) {
const b = sb.b;
const run = Build.Step.Run.create(b, "self-signed certificate");
run.addFileArg(sb.program(&sb.shared.openssl, &.{"openssl"}));
run.addArgs(&.{ "req", "-x509", "-newkey", "ec", "-pkeyopt", "ec_paramgen_curve:prime256v1", "-nodes", "-days", "3650", "-subj", "/CN=sketchbook" });
run.addArg("-keyout");
const key = run.addOutputFileArg("key.pem");
run.addArg("-out");
// Its progress on stderr is not a warning.
_ = run.captureStdErr(.{});
sb.shared.certificate = .{ .cert = run.addOutputFileArg("cert.pem"), .key = key };
}
return sb.shared.certificate.?;
}
/// `module` as the web build compiles it: each shader module in its
/// imports, however deep, replaced by its WGSL twin, and each module on
/// the way copied to import the copy. Modules nothing swaps below are
/// shared as they are.
fn webModule(sb: Sketchbook, module: *Build.Module, copies: *std.AutoArrayHashMapUnmanaged(*Build.Module, *Build.Module)) *Build.Module {
const arena = sb.b.graph.arena;
if (sb.shared.web_twins.get(module)) |twin| return twin;
if (copies.get(module)) |done| return done;
// An import cycle comes back here as itself: unchanged, which is
// right unless a shader module hides inside the cycle.
copies.put(arena, module, module) catch @panic("OOM");
var swapped = false;
const imports = arena.alloc(*Build.Module, module.import_table.count()) catch @panic("OOM");
for (module.import_table.values(), imports) |imported, *web| {
web.* = sb.webModule(imported, copies);
swapped = swapped or web.* != imported;
}
if (!swapped) return module;
const copy = arena.create(Build.Module) catch @panic("OOM");
copy.init(module.owner, .{ .existing = module });
copy.import_table = .empty;
copy.cached_graph = .{ .modules = &.{}, .names = &.{} };
for (module.import_table.keys(), imports) |name, web| copy.addImport(name, web);
copies.put(arena, module, copy) catch @panic("OOM");
return copy;
}
pub fn app(sb: Sketchbook, options: App.Options) App {
const imports = sb.b.allocator.alloc(Build.Module.Import, options.imports.len + 1) catch @panic("OOM");
imports[0] = .{ .name = "sketch", .module = sb.modules.sketch };
@memcpy(imports[1..], options.imports);
return .{
.sb = sb,
.name = options.name,
.root_source_file = options.root_source_file,
.imports = imports,
// No target: every artifact compiles it for its own.
.module = sb.b.createModule(.{ .root_source_file = options.root_source_file, .imports = imports }),
};
}
};
pub const App = struct {
sb: Sketchbook,
name: []const u8,
root_source_file: Build.LazyPath,
imports: []const Build.Module.Import,
/// The app's root, importing `sketch` and the app's own imports.
module: *Build.Module,
pub const Options = struct {
name: []const u8,
root_source_file: Build.LazyPath,
/// Imports for the app's root module, besides `sketch`: for example
/// `sb.modules.vector`, or shaders from `addSpirvModule`.
imports: []const Build.Module.Import = &.{},
};
/// A root module around the app: `source` sees `app`, `sketch` and `host`.
fn wrap(app: App, source: []const u8, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode) *Build.Module {
const b = app.sb.b;
const root = b.createModule(.{
.root_source_file = b.addWriteFiles().add("root.zig", source),
.target = target,
.optimize = optimize,
.imports = &.{ .{ .name = "app", .module = app.module }, .{ .name = "sketch", .module = app.sb.modules.sketch } },
});
if (std.mem.indexOf(u8, source, "\"host\"") != null) root.addImport("host", app.sb.modules.host);
return root;
}
/// The hot-reloadable sketch: a shared library the host watches.
pub fn addLibrary(app: App) *Build.Step.Compile {
return app.sb.b.addLibrary(.{
.name = app.name,
.linkage = .dynamic,
.root_module = app.wrap("comptime { @import(\"sketch\").exportSketch(@import(\"app\")); }", app.sb.target, app.sb.optimize),
});
}
/// Host and sketch in one executable, nothing loaded at runtime: for
/// shipping, and for scripts that must not depend on a library path.
pub fn addExecutable(app: App) *Build.Step.Compile {
return app.sb.b.addExecutable(.{
.name = app.name,
.root_module = app.wrap(
\\const std = @import("std");
\\pub fn main(init: std.process.Init) !void {
\\ return @import("host").main(init, @import("sketch").sketch(@import("app")));
\\}
, app.sb.target, app.sb.optimize),
});
}
pub const WebOptions = struct {
/// Directories copied next to the page, under their own `dest`.
assets: []const Asset = &.{},
/// Replaces the generic page; `{title}` is substituted either way,
/// and `{head}` with the links an installable app needs.
index_html: ?Build.LazyPath = null,
optimize: std.builtin.OptimizeMode = .ReleaseSafe,
/// Makes the page an installable app that opens offline.
pwa: ?Pwa = null,
pub const Asset = struct { source: Build.LazyPath, dest: []const u8 };
/// A progressive web app: a manifest naming it, icons, and a
/// service worker (`web/sw.js`) that keeps a copy of everything the
/// page fetches, network first, so it opens offline and still shows
/// each new build at once. Browsers allow service workers only in
/// secure contexts (https, or localhost).
pub const Pwa = struct {
/// The app's name by default.
name: ?[]const u8 = null,
short_name: ?[]const u8 = null,
description: []const u8 = "",
/// CSS colours: behind the page while it starts, and the
/// browser's chrome around it.
background: []const u8 = "#000000",
theme: []const u8 = "#000000",
/// Square PNGs, served as `icon-<size>.png`. Browsers want 192
/// and 512 pixels to offer installing.
icons: []const Icon = &.{},
pub const Icon = struct { source: Build.LazyPath, size: u32 };
};
};
pub const Web = struct {
wasm: *Build.Step.Compile,
/// The page: `index.html`, `host.js`, `sketch.wasm` and assets.
dir: Build.LazyPath,
};
/// The browser build, as one directory ready to serve.
pub fn addWeb(app: App, options: WebOptions) Web {
const b = app.sb.b;
var copies: std.AutoArrayHashMapUnmanaged(*Build.Module, *Build.Module) = .empty;
var web_app = app;
web_app.module = app.sb.webModule(app.module, &copies);
const wasm = b.addExecutable(.{
.name = "sketch",
.root_module = web_app.wrap("comptime { @import(\"sketch\").web.exportWeb(@import(\"app\")); }", b.resolveTargetQuery(.{ .cpu_arch = .wasm32, .os_tag = .freestanding }), options.optimize),
});
wasm.entry = .disabled;
wasm.rdynamic = true;
wasm.export_memory = true;
const files = b.addWriteFiles();
_ = files.addCopyFile(wasm.getEmittedBin(), "sketch.wasm");
_ = files.addCopyFile(app.sb.web.path(b, "host.js"), "host.js");
const page = b.addRunArtifact(b.addExecutable(.{
.name = "sketchbook-page",
.root_module = b.createModule(.{ .root_source_file = b.addWriteFiles().add("page.zig", page_tool), .target = b.graph.host }),
}));
page.addFileArg(options.index_html orelse app.sb.web.path(b, "index.html"));
page.addArg(app.name);
page.addArg(if (options.pwa) |pwa| app.addPwa(files, pwa) else "");
_ = files.addCopyFile(page.addOutputFileArg("index.html"), "index.html");
for (options.assets) |asset| _ = files.addCopyDirectory(asset.source, asset.dest, .{});
return .{ .wasm = wasm, .dir = files.getDirectory() };
}
/// Writes the manifest, icons and service worker into `files`, and
/// returns what the page's `<head>` needs for them.
fn addPwa(app: App, files: *Build.Step.WriteFile, pwa: WebOptions.Pwa) []const u8 {
const b = app.sb.b;
const arena = b.graph.arena;
const Icon = struct { src: []const u8, sizes: []const u8, type: []const u8 = "image/png", purpose: []const u8 = "any" };
const icons = arena.alloc(Icon, pwa.icons.len) catch @panic("OOM");
var touch: ?[]const u8 = null;
for (pwa.icons, icons) |icon, *entry| {
const name = b.fmt("icon-{d}.png", .{icon.size});
_ = files.addCopyFile(icon.source, name);
entry.* = .{ .src = name, .sizes = b.fmt("{d}x{d}", .{ icon.size, icon.size }) };
// iOS takes its home-screen icon from the page, not the manifest.
if (icon.size >= 180 and (touch == null or icon.size < 512)) touch = name;
}
const name = pwa.name orelse app.name;
const manifest = std.json.Stringify.valueAlloc(arena, .{
.name = name,
.short_name = pwa.short_name orelse name,
.description = pwa.description,
// Relative: the app works under any path it is served from.
.start_url = ".",
.scope = ".",
.display = "standalone",
.background_color = pwa.background,
.theme_color = pwa.theme,
.icons = icons,
}, .{ .whitespace = .indent_2 }) catch @panic("OOM");
_ = files.add("manifest.webmanifest", manifest);
_ = files.addCopyFile(app.sb.web.path(b, "sw.js"), "sw.js");
return b.fmt(
\\<link rel="manifest" href="manifest.webmanifest">
\\<meta name="theme-color" content="{s}">{s}
, .{ pwa.theme, if (touch) |icon| b.fmt("\n<link rel=\"apple-touch-icon\" href=\"{s}\">", .{icon}) else "" });
}
/// Serves an installed web build (`install`, under the prefix) with
/// `miniserve`, over https on port 8042 of every interface, until
/// stopped. Browsers give WebGPU and the microphone only to secure
/// contexts, and https makes the page one from any device on the
/// network, once the self-signed certificate is accepted; miniserve
/// prints the addresses as QR codes, for phones. It serves the installed
/// files, so `zig build web --watch` alongside shows each rebuild on
/// reload. Its defaults are environment variables, so miniserve's
/// options after `--` replace them (`-p 9000`).
pub fn addServe(app: App, install: *Build.Step.InstallDir) *Build.Step.Run {
const sb = app.sb;
const b = sb.b;
const prefix_relative = switch (install.options.install_dir) {
.prefix => install.options.install_subdir,
.custom => |dir| b.pathJoin(&.{ dir, install.options.install_subdir }),
else => @panic("addServe: install the web build under the prefix"),
};
const certificate = sb.certificate();
const run = Build.Step.Run.create(b, "miniserve");
run.addFileArg(sb.program(&sb.shared.miniserve, &.{"miniserve"}));
run.addPrefixedFileArg("--tls-cert=", certificate.cert);
run.addPrefixedFileArg("--tls-key=", certificate.key);
for ([_][2][]const u8{
.{ "MINISERVE_PORT", "8042" },
.{ "MINISERVE_INTERFACE", "0.0.0.0" },
.{ "MINISERVE_INDEX", "index.html" },
.{ "MINISERVE_DISABLE_INDEXING", "true" },
.{ "MINISERVE_QRCODE", "true" },
// A rebuilt sketch shows on reload.
.{ "MINISERVE_HEADER", "Cache-Control:no-cache" },
}) |env| run.setEnvironmentVariable(env[0], env[1]);
run.addPassthruArgs();
run.addDirectoryArg(b.graph.path(.install_prefix, prefix_relative));
run.step.dependOn(&install.step);
run.stdio = .inherit;
run.has_side_effects = true;
return run;
}
pub const RunOptions = struct {
/// State file, relative to the working directory.
state: ?[]const u8 = null,
/// Where relative asset paths resolve; the project root by default.
cwd: ?Build.LazyPath = null,
};
/// Runs the generic host on the installed library. Rebuilding the library
/// (`zig build lib --watch` in another terminal) reloads it in place.
pub fn addRun(app: App, library: *Build.Step.Compile, options: RunOptions) *Build.Step.Run {
const b = app.sb.b;
const install = b.addInstallArtifact(library, .{});
const run = b.addRunArtifact(app.sb.host_exe);
run.step.dependOn(&install.step);
run.addArgs(&.{ "--state", options.state orelse b.fmt("{s}.state", .{app.name}) });
run.addFileArg(b.graph.path(.install_lib, library.out_filename));
run.setCwd(options.cwd orelse b.path("."));
run.stdio = .inherit;
run.addPassthruArgs();
return run;
}
pub const ScriptOptions = struct {
/// `{name}` substitutions for the script.
defines: []const [2][]const u8 = &.{},
cwd: ?Build.LazyPath = null,
};
/// Plays a script headless, with a throwaway state file, against
/// `artifact`: the executable (`addExecutable`), or the hot-reloadable
/// library (`addLibrary`) through the generic host, which scripts can
/// `reload`. Fails when an expectation or a console line does.
pub fn addScript(app: App, artifact: *Build.Step.Compile, script: Build.LazyPath, options: ScriptOptions) *Build.Step.Run {
const b = app.sb.b;
const library = artifact.isDynamicLibrary();
const run = b.addRunArtifact(if (library) app.sb.host_exe else artifact);
run.addArgs(&.{ "--headless", "--fresh", "--script" });
run.addFileArg(script);
run.addArg("--state");
// Named per script: runs of one app may share an output directory.
_ = run.addOutputFileArg(b.fmt("{s}-{s}.state", .{ app.name, std.fs.path.stem(script.getDisplayName()) }));
for (options.defines) |pair| run.addArgs(&.{ "--define", b.fmt("{s}={s}", .{ pair[0], pair[1] }) });
if (library) run.addArtifactArg(artifact);
run.setCwd(options.cwd orelse b.path("."));
run.expectExitCode(0);
run.has_side_effects = true;
return run;
}
/// Prints the app's live state; `zig build probe -- --watch` follows it.
pub fn addProbe(app: App, state: ?[]const u8) *Build.Step.Run {
const b = app.sb.b;
const run = b.addRunArtifact(app.sb.probe_exe);
run.addArg(state orelse b.fmt("{s}.state", .{app.name}));
run.setCwd(b.path("."));
run.stdio = .inherit;
run.addPassthruArgs();
return run;
}
/// Tests in `root_source_file` (the app's root by default), with the
/// app's imports and the app itself importable as `app`.
pub fn addTest(app: App, options: struct { root_source_file: ?Build.LazyPath = null }) *Build.Step.Compile {
const b = app.sb.b;
const module = b.createModule(.{
.root_source_file = options.root_source_file orelse app.root_source_file,
.target = app.sb.target,
.optimize = app.sb.optimize,
.imports = app.imports,
});
if (options.root_source_file != null) module.addImport("app", app.module);
return b.addTest(.{ .root_module = module });
}
pub const StepsOptions = struct {
web: ?WebOptions = null,
/// Scripts run by the `e2e` step.
scripts: []const Build.LazyPath = &.{},
/// Extra test roots for the `test` step, besides the app's root.
tests: []const Build.LazyPath = &.{},
};
pub const Steps = struct {
library: *Build.Step.Compile,
exe: *Build.Step.Compile,
run: *Build.Step.Run,
web: ?Web,
test_step: *Build.Step,
e2e: *Build.Step,
};
/// The conventional wiring. Installs the executable, and adds:
/// `run` (host + hot reload), `lib` (rebuild the library; use `--watch`),
/// `web` and `serve` (with `web` options), `probe`, `e2e` (scripts) and
/// `test`.
pub fn addSteps(app: App, options: StepsOptions) Steps {
const b = app.sb.b;
const library = app.addLibrary();
const exe = app.addExecutable();
b.installArtifact(exe);
const run = app.addRun(library, .{});
b.step("run", "Run with hot reload (rebuild with `zig build lib --watch`)").dependOn(&run.step);
b.step("lib", "Build and install the hot-reloadable library").dependOn(&b.addInstallArtifact(library, .{}).step);
b.step("probe", "Print the live state (-- --watch to follow)").dependOn(&app.addProbe(null).step);
const web = if (options.web) |web_options| blk: {
const web = app.addWeb(web_options);
const install = b.addInstallDirectory(.{ .source_dir = web.dir, .install_dir = .prefix, .install_subdir = "web" });
b.step("web", "Build the browser version into zig-out/web").dependOn(&install.step);
b.step("serve", "Serve zig-out/web over https on port 8042, to the local network too (-- -p PORT for another)").dependOn(&app.addServe(install).step);
break :blk web;
} else null;
const e2e = b.step("e2e", "Play the end-to-end scripts headless");
for (options.scripts) |script| e2e.dependOn(&app.addScript(exe, script, .{}).step);
const test_step = b.step("test", "Run unit tests and end-to-end scripts");
test_step.dependOn(&b.addRunArtifact(app.addTest(.{})).step);
for (options.tests) |root| test_step.dependOn(&b.addRunArtifact(app.addTest(.{ .root_source_file = root })).step);
test_step.dependOn(e2e);
return .{ .library = library, .exe = exe, .run = run, .web = web, .test_step = test_step, .e2e = e2e };
}
};
/// Fills `{title}` and `{head}` in the page template.
const page_tool =
\\const std = @import("std");
\\pub fn main(init: std.process.Init) !void {
\\ var args = init.minimal.args.iterate();
\\ _ = args.skip();
\\ const template = args.next().?;
\\ const title = args.next().?;
\\ const head = args.next().?;
\\ const out = args.next().?;
\\ const cwd = std.Io.Dir.cwd();
\\ const arena = init.arena.allocator();
\\ const source = try cwd.readFileAlloc(init.io, template, arena, .limited(1 << 20));
\\ const titled = try std.mem.replaceOwned(u8, arena, source, "{title}", title);
\\ const page = try std.mem.replaceOwned(u8, arena, titled, "{head}", head);
\\ try cwd.writeFile(init.io, .{ .sub_path = out, .data = page });
\\}
;
|