summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 22:57:31 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit88c04dd6c392c6d8fc3a02408506e85d86f476d5 (patch)
tree4462fcb19dce110c24595f000bd8303c69288689
parent1cb36ee39a8bbc2cf61c28003670d760841d6d3e (diff)
downloadsketchbook-88c04dd6c392c6d8fc3a02408506e85d86f476d5.tar.gz
sketchbook-88c04dd6c392c6d8fc3a02408506e85d86f476d5.zip
Refuse a sketch library built by another compiler, backend or mode
abi.hash now covers the zig version, codegen backend and optimize mode: Zig's own calling convention (Host.VTable, every Allocator) differs between them, so a Debug host loading a ReleaseFast or LLVM library faulted on its first draw. Libraries export sketch_build, and the host's refusal says what differs and what to run instead.
-rw-r--r--README.md7
-rw-r--r--src/abi.zig17
-rw-r--r--src/host/library.zig20
-rw-r--r--src/sketch/root.zig3
4 files changed, 38 insertions, 9 deletions
diff --git a/README.md b/README.md
index 225f87c..8e4e430 100644
--- a/README.md
+++ b/README.md
@@ -874,8 +874,11 @@ renderer migration work and the optional addon boundary.
Host and sketch are built by the same `zig build`, so ordinary Zig types cross
it (slices, tagged unions, `std.mem.Allocator`). `abi.hash`, a comptime hash
-of every shared type's layout, guards against the one real hazard: a host
-refuses a library built against different definitions. Everything that outlives
+of every shared type's layout and of the zig version, backend and optimize
+mode, guards against the real hazards: a host refuses a library built
+against different definitions, or by another compiler or mode (`zig build
+run` beside `zig build lib --watch -Doptimize=fast`: Zig's own calling
+convention differs between them), and says what differs. Everything that outlives
a call lives in host memory, since host code is never unloaded. Only the
recorded `Event` and the reflected `Layout` are `extern`, because they are
written to disk.
diff --git a/src/abi.zig b/src/abi.zig
index 7177f14..33f7cd6 100644
--- a/src/abi.zig
+++ b/src/abi.zig
@@ -5,11 +5,13 @@
//! tagged unions, `std.mem.Allocator`. Two rules keep reloads safe:
//! - whatever outlives a call lives in host memory (host code is never
//! unloaded, so host allocators and function pointers stay valid);
-//! - `hash` covers the layout of every type here, and a host refuses a sketch
-//! built against different definitions instead of misreading its memory.
+//! - `hash` covers the layout of every type here and the compiler, backend
+//! and mode, and a host refuses a sketch built against different
+//! definitions or by another build instead of misreading its memory.
//!
//! Only `Event` and the reflected `Layout` are `extern`: they are written to disk.
const std = @import("std");
+const builtin = @import("builtin");
pub const layout = @import("layout.zig");
pub const Key = @import("keys.zig").Key;
@@ -813,16 +815,23 @@ pub const Sketch = struct {
};
};
-/// Layout hash of everything above. Changes whenever a shared type does.
+/// Layout hash of everything above, and of `build`. Changes whenever a shared
+/// type does, or the compiler, backend or optimize mode: Zig's own calling
+/// convention, which `Host.VTable` and every `std.mem.Allocator` use, differs
+/// between backends and modes.
pub const hash: u64 = blk: {
@setEvalBranchQuota(1_000_000);
var h: u64 = 0;
for (.{ Rect, Color, BlendMode, Corners, Event, Mode, Stream, Input, Image, Audio, Cursor, Voice, Command, gpu.Pass, gpu.Pipeline, gpu.Draw, gpu.Dispatch, gpu.PostProcess, Host, Host.VTable, Context, Field, Layout, Info, Memory, Sketch }) |T| {
h = std.hash.Wyhash.hash(h, @typeName(T) ++ layout.signature(T));
}
- break :blk h;
+ break :blk std.hash.Wyhash.hash(h, build);
};
+/// The compiler, backend and mode of this build, exported by libraries as
+/// `sketch_build` so a host can say why it refuses one.
+pub const build = builtin.zig_version_string ++ " " ++ @tagName(builtin.zig_backend) ++ " " ++ @tagName(builtin.mode);
+
test "vertex attributes and std140 checks come from the types" {
const Vertex = extern struct { position: [2]f32, color: [4]u8, uv: [2]f32 };
const attrs = gpu.attributes(Vertex);
diff --git a/src/host/library.zig b/src/host/library.zig
index 6958eec..f8bc4e8 100644
--- a/src/host/library.zig
+++ b/src/host/library.zig
@@ -13,7 +13,8 @@ pub const Library = struct {
object: *c.SDL_SharedObject,
sketch: abi.Sketch,
- pub fn open(path: [:0]const u8) !Library {
+ /// Loads the library at `path`; `source` names it in messages.
+ pub fn open(path: [:0]const u8, source: []const u8) !Library {
const object = c.SDL_LoadObject(path.ptr) orelse return error.LoadLibrary;
errdefer c.SDL_UnloadObject(object);
var sketch: abi.Sketch = undefined;
@@ -22,7 +23,20 @@ pub const Library = struct {
const address = c.SDL_LoadFunction(object, symbol) orelse return error.MissingEntryPoint;
@field(sketch, name) = @ptrCast(address);
}
- if (sketch.info().abi != abi.hash) return error.AbiMismatch;
+ if (sketch.info().abi != abi.hash) {
+ const address = c.SDL_LoadFunction(object, "sketch_build") orelse {
+ std.log.err("{s}: built by an older sketchbook: rebuild it", .{source});
+ return error.AbiMismatch;
+ };
+ const build = std.mem.span(@as([*:0]const u8, @ptrFromInt(@intFromPtr(address))));
+ if (std.mem.eql(u8, build, abi.build)) {
+ std.log.err("{s}: built against other abi types: restart the host to load it", .{source});
+ } else {
+ const mode = build[std.mem.lastIndexOfScalar(u8, build, ' ').? + 1 ..];
+ std.log.err("{s}: built by zig {s}, this host by zig {s}; Zig calls cross the boundary, so both need the same compiler, backend and mode: build the host like the library (`zig build run -Doptimize={s}`) or the library like the host", .{ source, build, abi.build, mode });
+ }
+ return error.AbiMismatch;
+ }
return .{ .object = object, .sketch = sketch };
}
@@ -33,7 +47,7 @@ pub const Library = struct {
const cwd = std.Io.Dir.cwd();
try cwd.copyFile(source, cwd, copy, io, .{});
defer cwd.deleteFile(io, copy) catch {};
- return open(copy);
+ return open(copy, source);
}
pub fn close(self: *Library) void {
diff --git a/src/sketch/root.zig b/src/sketch/root.zig
index cb20ab9..bc09add 100644
--- a/src/sketch/root.zig
+++ b/src/sketch/root.zig
@@ -317,6 +317,7 @@ pub fn exportSketch(comptime App: type) void {
@export(&G.update, .{ .name = names.update });
@export(&G.draw, .{ .name = names.draw });
@export(&G.command, .{ .name = names.command });
+ @export(&G.build, .{ .name = "sketch_build" });
}
pub fn Glue(comptime App: type) type {
@@ -325,6 +326,8 @@ pub fn Glue(comptime App: type) type {
pub const Session = if (@hasDecl(App, "Session")) App.Session else struct {};
pub const Store = if (@hasDecl(App, "Store")) App.Store else struct {};
+ const build: [abi.build.len:0]u8 = abi.build.*;
+
pub const description: abi.Info = .{
.abi = abi.hash,
.name = if (@hasDecl(App, "name")) App.name else "sketch",