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
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
|
//! 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") });
// Geometry and noise, shared by the sketch library and `vector`.
const math = b.addModule("math", .{ .root_source_file = b.path("src/math/root.zig") });
const sketch_imports: []const Build.Module.Import = &.{ .{ .name = "abi", .module = abi }, .{ .name = "math", .module = math } };
const sketch = b.addModule("sketch", .{ .root_source_file = b.path("src/sketch/root.zig"), .imports = sketch_imports });
const c = cModule(b, target, optimize);
// No optimize mode of its own: the host's Zig code builds in the mode
// of the executable it is part of (`script_optimize` makes use of it).
const host = b.addModule("host", .{
.root_source_file = b.path("src/host/root.zig"),
.target = target,
.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"), .tools = b.path("tools"), .script_optimize = optimize, .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", "Painted", "Viewport", "Paint" } },
.sources = &.{ b.path("src/vector/shaders/path.vert"), b.path("src/vector/shaders/stencil.frag"), b.path("src/vector/shaders/paint.vert"), b.path("src/vector/shaders/paint.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 = "math", .module = math },
.{ .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 = sketch_imports }),
b.createModule(.{ .root_source_file = b.path("src/math/root.zig"), .target = target, .optimize = optimize }),
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);
// The noise tests again on wasm32 as the web builds it, under Node's
// WASI: the golden bits must come out the same in the browser as
// natively. (Only noise: LLVM 21 cannot select code for one of the
// Bézier tests' vector constants on wasm32 in release modes.)
const wasm_math = b.addTest(.{ .root_module = b.createModule(.{
.root_source_file = b.path("src/math/noise.zig"),
.target = b.resolveTargetQuery(.{ .cpu_arch = .wasm32, .os_tag = .wasi }),
.optimize = .ReleaseSafe,
}) });
const wasi = Build.Step.Run.create(b, "noise tests on wasm32-wasi");
wasi.addFileArg(sb.program(&sb.shared.node, &.{"node"}));
wasi.addArg("--no-warnings");
wasi.addFileArg(b.path("tools/wasi_run.mjs"));
wasi.addArtifactArg(wasm_math);
// The test runner's progress is not a warning.
_ = wasi.captureStdErr(.{});
wasi.expectExitCode(0);
test_step.dependOn(&wasi.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();
// Command.shape on the native host: the parity cases, screenshotted
// and checked pixel by pixel (tools/shapes_web.mjs compares the same
// sketch in headless Chrome: `zig build test-web`).
const shapes = sb.app(.{ .name = "shapes", .root_source_file = b.path("test/shapes.zig") });
const shapes_native = shapes.addScript(shapes.addExecutable(), b.path("test/shapes.script"), .{});
test_step.dependOn(&shapes_native.step);
const shapes_web = Build.Step.Run.create(b, "shapes in headless Chrome");
shapes_web.addFileArg(sb.program(&sb.shared.node, &.{"node"}));
shapes_web.addFileArg(b.path("tools/shapes_web.mjs"));
shapes_web.addDirectoryArg(shapes.addWeb(.{}).dir);
shapes_web.addFileArg(b.path(".zig-cache/shapes/native.png"));
shapes_web.addFileArg(b.findProgramLazy(.{ .names = &.{ "google-chrome-stable", "google-chrome", "chromium", "chromium-browser" } }));
shapes_web.step.dependOn(&shapes_native.step);
shapes_web.has_side_effects = true;
shapes_web.expectExitCode(0);
const test_web = b.step("test-web", "Compare shapes, targets, blending and images in headless Chrome with the native host, and time 5000 circles");
test_web.dependOn(&shapes_web.step);
// Targets, blend modes, image placement and tint, colours per subpath
// (test/render.zig): natively, checked pixel by pixel, and in Chrome.
const render = sb.app(.{ .name = "render", .root_source_file = b.path("test/render.zig") });
const render_native = render.addScript(render.addExecutable(), b.path("test/render.script"), .{});
test_step.dependOn(&render_native.step);
const render_web = Build.Step.Run.create(b, "render in headless Chrome");
render_web.addFileArg(sb.program(&sb.shared.node, &.{"node"}));
render_web.addFileArg(b.path("tools/render_web.mjs"));
render_web.addDirectoryArg(render.addWeb(.{}).dir);
render_web.addFileArg(b.path(".zig-cache/render/native.png"));
render_web.addFileArg(b.findProgramLazy(.{ .names = &.{ "google-chrome-stable", "google-chrome", "chromium", "chromium-browser" } }));
render_web.step.dependOn(&render_native.step);
render_web.has_side_effects = true;
render_web.expectExitCode(0);
test_web.dependOn(&render_web.step);
// `Host.textSize` against the text drawn (test/text.zig).
const text = sb.app(.{ .name = "text", .root_source_file = b.path("test/text.zig") });
test_step.dependOn(&text.addScript(text.addExecutable(), b.path("test/text.script"), .{}).step);
// The examples, so they always compile.
for ([_][]const u8{ "pen", "flock" }) |example| {
test_step.dependOn(&sb.app(.{ .name = example, .root_source_file = b.path(b.fmt("examples/{s}.zig", .{example})) }).addLibrary().step);
}
// 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);
// Export: two builds of one sketch export the same frames, on the
// export's own clock (test/export.script); the raw stream is as long as
// its frames, up to where the sketch quits; and ffmpeg, if there is
// one, makes a video of it with as many.
const export_a = sb.app(.{ .name = "export-a", .root_source_file = b.path("test/export.zig") });
const export_b = sb.app(.{ .name = "export-b", .root_source_file = b.path("test/export.zig") });
const export_exe = export_a.addExecutable();
const export_options: App.ExportOptions = .{ .fps = 30, .frames = 5, .size = .{ 320, 180 } };
const exported = export_a.addScript(export_exe, b.path("test/export.script"), .{});
exported.addArg("--define");
exported.addPrefixedDirectoryArg("a=", export_a.addExport(export_exe, export_options).frames);
exported.addArg("--define");
exported.addPrefixedDirectoryArg("b=", export_b.addExport(export_b.addExecutable(), export_options).frames);
test_step.dependOn(&exported.step);
const raw = b.addSystemCommand(&.{ "sh", "-c",
\\set -e
\\test "$("$0" --state "$1" --export - --fps 30 --size 320x180 | wc -c)" = $((320 * 180 * 4 * 8))
\\command -v ffmpeg >/dev/null && command -v ffprobe >/dev/null || exit 0
\\"$0" --state "$1" --export - --fps 30 --size 320x180 | ffmpeg -loglevel error -y -f rawvideo -pix_fmt rgba -s 320x180 -r 30 -i - -pix_fmt yuv420p "$2"
\\test "$(ffprobe -v error -count_frames -select_streams v:0 -show_entries stream=nb_read_frames -of csv=p=0 "$2")" = 8
});
raw.addArtifactArg(export_exe);
_ = raw.addOutputFileArg("raw.state");
_ = raw.addOutputFileArg("raw.mp4");
raw.expectExitCode(0);
test_step.dependOn(&raw.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);
// Recorded input replays to the same state: played, seeked, stepped,
// and after a live pointer move (core host behaviour, not an API).
const replay = b.addRunArtifact(host_exe);
replay.addArgs(&.{ "--headless", "--fresh", "--script" });
replay.addFileArg(b.path("test/replay.script"));
replay.addArg("--state");
_ = replay.addOutputFileArg("replay.state");
replay.addArtifactArg(sb.app(.{ .name = "replay", .root_source_file = b.path("test/replay.zig") }).addLibrary());
replay.expectExitCode(0);
test_step.dependOn(&replay.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"));
fixSdlVulkanAllocationLeak(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.? });
}
/// SDL 3.4's Vulkan backend leaks a memory allocation's region list and
/// mutex when `vkAllocateMemory` fails (SDL_gpu_vulkan.c,
/// `VULKAN_INTERNAL_AllocateMemory`), which it then survives by trying
/// another memory type. Many headless hosts at once (parallel `e2e`) run
/// small heaps out, and the leak check failed random scripts. The file is
/// compiled from a copy with the two frees added.
fn fixSdlVulkanAllocationLeak(b: *Build, sdl: *Build.Module, source: Build.LazyPath) void {
const file = "src/gpu/vulkan/SDL_gpu_vulkan.c";
var found = false;
var flags: []const []const u8 = &.{};
for (sdl.link_objects.items) |object| {
if (object != .c_source_files) continue;
const group = object.c_source_files;
for (group.files, 0..) |f, i| {
if (!std.mem.eql(u8, f, file)) 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;
found = true;
break;
}
}
if (!found) return;
const tool = b.addExecutable(.{ .name = "reload-edit", .root_module = b.createModule(.{
.root_source_file = b.path("tools/reload_edit.zig"),
.target = b.graph.host,
}) });
const edit = b.addRunArtifact(tool);
edit.setName("patch SDL_gpu_vulkan.c");
edit.addDirectoryArg(source.path(b, "gpu/vulkan"));
const out = edit.addOutputDirectoryArg("vulkan");
edit.addArgs(&.{
"SDL_gpu_vulkan.c",
" // Uh oh, we couldn't allocate, time to clean up\n SDL_free(allocation->freeRegions);\n",
" // Uh oh, we couldn't allocate, time to clean up\n SDL_free(allocation->freeRegions);\n SDL_free(allocation->usedRegions);\n SDL_DestroyMutex(allocation->memoryLock);\n",
});
// The copy's relative includes (`../SDL_sysgpu.h`) resolve from the
// original directory.
sdl.addIncludePath(source.path(b, "gpu/vulkan"));
sdl.addIncludePath(source);
sdl.addCSourceFile(.{ .file = out.path(b, "SDL_gpu_vulkan.c"), .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",
/// The optimize mode of the executables `e2e` plays scripts with
/// (`App.addScriptExecutable`); `optimize` when null. Pass it a
/// `b.option`, say `-Dscript-optimize=ReleaseSafe`, when Debug is too
/// slow for a sketch's scripts. Only the host's and the app's Zig code
/// change mode; SDL and the C pieces keep `optimize`.
script_optimize: ?std.builtin.OptimizeMode = null,
};
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"),
.tools = dep.path("tools"),
.script_optimize = options.script_optimize orelse options.optimize,
.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,
/// How each shader module was made, so `addReloadCheck` can make it
/// again from edited sources.
recipes: std.AutoArrayHashMapUnmanaged(*Build.Module, Recipe) = .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,
node: ?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 };
const Recipe = union(enum) { glsl: Sketchbook.ShaderOptions, zig: Sketchbook.ZigShaderOptions };
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,
/// Build-time tools (`spirv_strip.zig`, `reload_edit.zig`, ...).
tools: Build.LazyPath,
/// The optimize mode of executables that play scripts (`e2e`): Debug
/// is slow for per-pixel loops, and that is often the only reason to
/// build a script run differently from the rest.
script_optimize: std.builtin.OptimizeMode,
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 = fileName(options.source);
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 const ShaderOptions = 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 = &.{},
};
pub fn addShaders(sb: Sketchbook, options: ShaderOptions) 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 = fileName(source);
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");
var kept = options;
kept.sources = b.graph.arena.dupe(Build.LazyPath, options.sources) catch @panic("OOM");
kept.include_dirs = b.graph.arena.dupe(Build.LazyPath, options.include_dirs) catch @panic("OOM");
sb.shared.recipes.put(b.graph.arena, shaders.module, .{ .glsl = kept }) catch @panic("OOM");
return shaders;
}
pub const ZigShaderOptions = struct {
/// One shader per file, its entry point `export fn main` with a
/// SPIR-V calling convention (`.spirv_fragment`, `.spirv_vertex`).
sources: []const Build.LazyPath,
/// Modules the shaders import (shared uniform structs, helpers).
imports: []const Build.Module.Import = &.{},
};
/// Shaders written in Zig, as `addShaders` makes them from GLSL: the
/// same `Shaders` (SPIR-V module, WGSL twin swapped in for the web), so
/// a sketch cannot tell which language a shader came from. `fill.zig`
/// is declared as `fill`.
///
/// Each source is compiled by Zig's own SPIR-V backend. The steps, and
/// why each one is there:
/// - target `spirv32-vulkan`: `spirv64` asks for physical storage
/// buffer pointers, which naga refuses;
/// - the self-hosted backend (`use_llvm = false`), ReleaseFast: through
/// LLVM the object comes out empty, without an error;
/// - `tools/spirv_strip.zig` then drops the `Aligned` memory operands
/// Zig puts on every OpLoad/OpStore: Vulkan accepts them, naga's
/// SPIR-V reader does not ("invalid operand count");
/// - for the web, `naga --keep-coordinate-space` translates the
/// stripped SPIR-V to WGSL, as for GLSL.
///
/// What shader code can be: no table-driven `std.math` (`atan2` indexes
/// const tables through generic pointers, which logical addressing
/// forbids: call GLSL.std.450 through inline assembly), and no
/// `@Vector` in an `extern struct` shared with the CPU (use `[2]f32`
/// there and `@Vector` only when `builtin.cpu.arch.isSpirV()`; std140
/// wants a vec2 array stride of 16, which a `[2]f32` array lacks).
pub fn addZigShaders(sb: Sketchbook, options: ZigShaderOptions) Shaders {
const b = sb.b;
const spirv = b.resolveTargetQuery(.{ .cpu_arch = .spirv32, .os_tag = .vulkan });
const strip = b.addExecutable(.{ .name = "spirv-strip", .root_module = b.createModule(.{
.root_source_file = sb.tools.path(b, "spirv_strip.zig"),
.target = b.graph.host,
}) });
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 name = std.fs.path.stem(fileName(source));
const object = b.addObject(.{
.name = name,
.root_module = b.createModule(.{ .root_source_file = source, .target = spirv, .optimize = .ReleaseFast, .imports = options.imports }),
.use_llvm = false,
});
const stripped = b.addRunArtifact(strip);
stripped.addFileArg(object.getEmittedBin());
const spv = stripped.addOutputFileArg(b.fmt("{s}.spv", .{name}));
_ = native.addCopyFile(spv, 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}", .{fileName(source)}));
translate.addFileArg(sb.naga());
translate.addArg("--keep-coordinate-space");
translate.addFileArg(spv);
_ = 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");
sb.shared.recipes.put(b.graph.arena, shaders.module, .{ .zig = .{
.sources = b.graph.arena.dupe(Build.LazyPath, options.sources) catch @panic("OOM"),
.imports = b.graph.arena.dupe(Build.Module.Import, options.imports) catch @panic("OOM"),
} }) 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.
pub 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.executable(app.sb.optimize);
}
/// The executable as scripts play it: built in `script_optimize` mode
/// (see `Options`), the same as `addExecutable` unless that was set.
pub fn addScriptExecutable(app: App) *Build.Step.Compile {
return app.executable(app.sb.script_optimize);
}
fn executable(app: App, optimize: std.builtin.OptimizeMode) *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, 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;
}
pub const ExportOptions = struct {
fps: u32 = 60,
/// Null: until the sketch quits (`f.quit()`).
frames: ?u64 = null,
/// The canvas of a sketch that takes the room it is given.
size: ?[2]u32 = null,
};
pub const Export = struct {
run: *Build.Step.Run,
/// `000000.png`, `000001.png`, ...
frames: Build.LazyPath,
};
/// Exports the frames of `exe` (`addExecutable`) as PNGs into a
/// directory of the cache: headless, from fresh state, frame k at
/// k/fps seconds whatever the wall clock does.
pub fn addExport(app: App, exe: *Build.Step.Compile, options: ExportOptions) Export {
const b = app.sb.b;
const run = b.addRunArtifact(exe);
run.addArg("--state");
_ = run.addOutputFileArg(b.fmt("{s}-export.state", .{app.name}));
run.addArg("--export");
const frames = run.addOutputDirectoryArg("frames");
run.addArgs(&.{ "--fps", b.fmt("{d}", .{options.fps}) });
if (options.frames) |n| run.addArgs(&.{ "--frames", b.fmt("{d}", .{n}) });
if (options.size) |size| run.addArgs(&.{ "--size", b.fmt("{d}x{d}", .{ size[0], size[1] }) });
run.setCwd(b.path("."));
run.expectExitCode(0);
return .{ .run = run, .frames = frames };
}
/// 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 Edit = struct {
/// Relative to the app's build root, as given to `b.path`: a Zig
/// source, a GLSL source, or a Zig shader source the app builds.
file: []const u8,
/// Must occur exactly once in `file`, or the build fails.
old: []const u8,
new: []const u8,
};
pub const ReloadCheck = struct {
run: *Build.Step.Run,
/// The library as written, and as edited.
library: *Build.Step.Compile,
edited: *Build.Step.Compile,
};
/// Checks that the app hot-reloads with its State kept: builds its
/// library as written, and again from a copy of its sources with
/// `edits` applied, then plays `script` headless through the generic
/// host on the first, with `{v2}` defined as the second, so the script
/// can `load {v2}` midway and check that State carried over (and, with
/// `expect-different-screenshot`, that the edit shows).
///
/// The copy covers the directory of every source an edited file is in
/// (a module's root's directory holds what it imports), and every
/// module and shader set (`addShaders`, `addZigShaders`) built from it
/// is built again from the copy, so edits to Zig code, GLSL and Zig
/// shaders all reach the second library.
pub fn addReloadCheck(app: App, options: struct {
script: Build.LazyPath,
edits: []const Edit,
}) ReloadCheck {
const b = app.sb.b;
var remap: Remap = .{ .sb = app.sb };
remap.collect(app.module);
for (options.edits) |edit| remap.cover(edit);
remap.makeCopies(options.edits);
var edited_app = app;
edited_app.module = remap.remapModule(app.module);
const library = app.addLibrary();
const edited = edited_app.addLibrary();
const run = b.addRunArtifact(app.sb.host_exe);
run.setName(b.fmt("reload check {s}", .{options.script.getDisplayName()}));
run.addArgs(&.{ "--headless", "--fresh", "--script" });
run.addFileArg(options.script);
run.addArg("--state");
_ = run.addOutputFileArg(b.fmt("{s}-{s}.state", .{ app.name, std.fs.path.stem(options.script.getDisplayName()) }));
run.addArg("--define");
run.addPrefixedArtifactArg("v2=", edited);
run.addArtifactArg(library);
run.setCwd(b.path("."));
run.expectExitCode(0);
run.has_side_effects = true;
return .{ .run = run, .library = library, .edited = edited };
}
/// The app's module graph, with the sources under some directories
/// replaced by edited copies (see `addReloadCheck`).
const Remap = struct {
sb: Sketchbook,
/// Source directories (relative to the build root) the graph uses.
dirs: std.ArrayList([]const u8) = .empty,
/// The directories copied, and their edited copies.
roots: std.ArrayList([]const u8) = .empty,
copies: std.ArrayList(Build.LazyPath) = .empty,
seen: std.AutoArrayHashMapUnmanaged(*Build.Module, void) = .empty,
done: std.AutoArrayHashMapUnmanaged(*Build.Module, *Build.Module) = .empty,
fn arena(r: *Remap) std.mem.Allocator {
return r.sb.b.graph.arena;
}
fn ours(r: *Remap, path: Build.LazyPath) ?[]const u8 {
return switch (path) {
.src_path => |p| if (p.owner == r.sb.b) p.sub_path else null,
else => null,
};
}
fn note(r: *Remap, path: ?Build.LazyPath) void {
const sub = r.ours(path orelse return) orelse return;
r.dirs.append(r.arena(), std.fs.path.dirname(sub) orelse ".") catch @panic("OOM");
}
fn collect(r: *Remap, m: *Build.Module) void {
if ((r.seen.getOrPut(r.arena(), m) catch @panic("OOM")).found_existing) return;
if (r.sb.shared.recipes.get(m)) |recipe| switch (recipe) {
.glsl => |o| {
for (o.sources) |src| r.note(src);
if (o.layouts) |l| r.collect(l.module);
},
.zig => |o| {
for (o.sources) |src| r.note(src);
for (o.imports) |i| r.collect(i.module);
},
};
r.note(m.root_source_file);
for (m.import_table.values()) |i| r.collect(i);
}
fn under(dir: []const u8, path: []const u8) bool {
if (std.mem.eql(u8, dir, ".")) return true;
return path.len > dir.len and std.mem.startsWith(u8, path, dir) and path[dir.len] == '/';
}
/// Picks the outermost source directory holding `edit.file`.
fn cover(r: *Remap, edit: Edit) void {
var best: ?[]const u8 = null;
for (r.dirs.items) |dir| if (under(dir, edit.file) and (best == null or under(dir, best.?))) {
best = dir;
};
const dir = best orelse std.debug.panic("addReloadCheck: {s} is in no directory of a source the app builds", .{edit.file});
for (r.roots.items) |*root| {
if (under(root.*, dir) or std.mem.eql(u8, root.*, dir)) return;
if (under(dir, root.*)) {
root.* = dir;
return;
}
}
r.roots.append(r.arena(), dir) catch @panic("OOM");
}
fn makeCopies(r: *Remap, edits: []const Edit) void {
const b = r.sb.b;
const tool = b.addExecutable(.{ .name = "reload-edit", .root_module = b.createModule(.{
.root_source_file = r.sb.tools.path(b, "reload_edit.zig"),
.target = b.graph.host,
}) });
for (r.roots.items) |root| {
// Copied first: the copy's directory is named by its
// contents, so the edit below reruns whenever they change.
const copy = b.addWriteFiles();
const source = copy.addCopyDirectory(b.path(root), "", .{});
const run = b.addRunArtifact(tool);
run.setName(b.fmt("edit a copy of {s}", .{root}));
run.addDirectoryArg(source);
const out = run.addOutputDirectoryArg("src");
for (edits) |edit| {
if (!under(root, edit.file)) continue;
run.addArgs(&.{ if (std.mem.eql(u8, root, ".")) edit.file else edit.file[root.len + 1 ..], edit.old, edit.new });
}
r.copies.append(r.arena(), out) catch @panic("OOM");
}
}
fn remapPath(r: *Remap, original: Build.LazyPath) Build.LazyPath {
const sub = r.ours(original) orelse return original;
for (r.roots.items, r.copies.items) |root, copy| {
if (!under(root, sub)) continue;
return copy.path(r.sb.b, if (std.mem.eql(u8, root, ".")) sub else sub[root.len + 1 ..]);
}
return original;
}
fn paths(r: *Remap, originals: []const Build.LazyPath, changed: *bool) []const Build.LazyPath {
const out = r.arena().alloc(Build.LazyPath, originals.len) catch @panic("OOM");
for (originals, out) |o, *p| {
p.* = r.remapPath(o);
changed.* = changed.* or std.meta.activeTag(p.*) != std.meta.activeTag(o);
}
return out;
}
fn remapModule(r: *Remap, m: *Build.Module) *Build.Module {
if (r.done.get(m)) |copy| return copy;
r.done.put(r.arena(), m, m) catch @panic("OOM");
var changed = false;
const result = if (r.sb.shared.recipes.get(m)) |recipe| switch (recipe) {
.glsl => |o| blk: {
var e = o;
e.sources = r.paths(o.sources, &changed);
if (o.layouts) |l| {
e.layouts = .{ .module = r.remapModule(l.module), .types = l.types };
changed = changed or e.layouts.?.module != l.module;
}
break :blk if (changed) r.sb.addShaders(e).module else m;
},
.zig => |o| blk: {
var e = o;
e.sources = r.paths(o.sources, &changed);
const imports = r.arena().alloc(Build.Module.Import, o.imports.len) catch @panic("OOM");
for (o.imports, imports) |i, *out| {
out.* = .{ .name = i.name, .module = r.remapModule(i.module) };
changed = changed or out.module != i.module;
}
e.imports = imports;
break :blk if (changed) r.sb.addZigShaders(e).module else m;
},
} else blk: {
const root = if (m.root_source_file) |file| r.remapPath(file) else null;
if (m.root_source_file) |file| changed = std.meta.activeTag(root.?) != std.meta.activeTag(file);
const imports = r.arena().alloc(*Build.Module, m.import_table.count()) catch @panic("OOM");
for (m.import_table.values(), imports) |i, *out| {
out.* = r.remapModule(i);
changed = changed or out.* != i;
}
if (!changed) break :blk m;
const copy = r.arena().create(Build.Module) catch @panic("OOM");
copy.init(m.owner, .{ .existing = m });
copy.root_source_file = root;
copy.import_table = .empty;
copy.cached_graph = .{ .modules = &.{}, .names = &.{} };
for (m.import_table.keys(), imports) |name, i| copy.addImport(name, i);
break :blk copy;
};
r.done.put(r.arena(), m, result) catch @panic("OOM");
return result;
}
};
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`, `export` (frames
/// for ffmpeg), `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;
// `--export` takes the first argument after `--`.
const exporting = b.addRunArtifact(exe);
exporting.addArgs(&.{ "--state", b.fmt("{s}.state", .{app.name}), "--export" });
exporting.addPassthruArgs();
exporting.setCwd(b.path("."));
exporting.stdio = .inherit;
b.step("export", "Export frames: -- DIR for PNGs, or - for raw RGBA on stdout; then --fps N, --frames N, --size WxH").dependOn(&exporting.step);
const e2e = b.step("e2e", "Play the end-to-end scripts headless");
const script_exe = if (app.sb.script_optimize == app.sb.optimize) exe else app.addScriptExecutable();
for (options.scripts) |script| e2e.dependOn(&app.addScript(script_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 };
}
};
/// A source's file name, for naming what is made from it: also for a file
/// inside a generated directory (an edited copy, see `addReloadCheck`),
/// whose display name would be "generated".
fn fileName(path: Build.LazyPath) []const u8 {
return switch (path) {
.generated => |g| if (g.sub_path.len > 0) std.fs.path.basename(g.sub_path) else path.getDisplayName(),
else => std.fs.path.basename(path.getDisplayName()),
};
}
/// 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 });
\\}
;
|