feat(examples): add Zig version compatibility layer

- create compat module to handle Zig 0.15 and 0.16 API differences
- update build system to include and distribute compat module to examples
- replace version-specific std.time and std.io calls with compatibility wrappers

Author: jinzhongjia

build.zig

@@ -86,8 +86,13 @@ pub fn build(b: *Build) !void {
     // Setup documentation generation
     generate_docs(b, optimize, target, flags_module);
 
+    // Create compatibility module for Zig version differences
+    const compat_module = b.addModule("compat", .{
+        .root_source_file = b.path(b.pathJoin(&.{ "examples", "compat.zig" })),
+    });
+
     // Build example applications
-    build_examples(b, optimize, target, webui_module, webui.artifact("webui")) catch |err| {
+    build_examples(b, optimize, target, webui_module, compat_module, webui.artifact("webui")) catch |err| {
         log.err("failed to build examples: {}", .{err});
         std.process.exit(1);
     };
@@ -126,7 +131,7 @@ fn generate_docs(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarget
 }
 
 // Function to build all example applications
-fn build_examples(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarget, webui_module: *Module, webui_lib: *Compile) !void {
+fn build_examples(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarget, webui_module: *Module, compat_module: *Module, webui_lib: *Compile) !void {
 
     // Get the absolute path to the examples directory
     var lazy_path = b.path("examples");
@@ -174,8 +179,9 @@ fn build_examples(b: *Build, optimize: OptimizeMode, target: Build.ResolvedTarge
             }),
         });
 
-        // Add the webui module and link against the library
+        // Add the webui and compat modules and link against the library
         exe.root_module.addImport("webui", webui_module);
+        exe.root_module.addImport("compat", compat_module);
         exe.linkLibrary(webui_lib);
 
         // Setup installation

examples/advanced_window/main.zig

@@ -1,6 +1,7 @@
 const std = @import("std");
 const webui = @import("webui");
 const builtin = @import("builtin");
+const compat = @import("compat");
 
 pub fn main() !void {
     const window = webui.newWindow();
@@ -105,7 +106,7 @@ fn getPortInfo(e: *webui.Event) void {
     const window = e.getWindow();
 
     var buffer: [256]u8 = undefined;
-    var fbs = std.io.fixedBufferStream(&buffer);
+    var fbs = compat.fixedBufferStream(&buffer);
     const writer = fbs.writer();
 
     const port = window.getPort() catch 0;
@@ -125,7 +126,7 @@ fn getProcessInfo(e: *webui.Event) void {
     const window = e.getWindow();
 
     var buffer: [512]u8 = undefined;
-    var fbs = std.io.fixedBufferStream(&buffer);
+    var fbs = compat.fixedBufferStream(&buffer);
     const writer = fbs.writer();
 
     const parent_pid = window.getParentProcessId() catch 0;

examples/compat.zig

@@ -0,0 +1,92 @@
+//! Compatibility layer for Zig 0.15 and 0.16
+const std = @import("std");
+const builtin = @import("builtin");
+
+// Check Zig version
+const zig_version = builtin.zig_version;
+const is_zig_0_16_or_later = zig_version.minor >= 16;
+
+// C time function fallback for Zig 0.16
+extern "c" fn time(tloc: ?*i64) i64;
+
+/// Get current Unix timestamp in seconds
+pub fn timestamp() i64 {
+    if (is_zig_0_16_or_later) {
+        // Zig 0.16: use C time function
+        return time(null);
+    } else {
+        // Zig 0.15 and earlier
+        return std.time.timestamp();
+    }
+}
+
+/// Get current timestamp in nanoseconds
+pub fn nanoTimestamp() i128 {
+    if (is_zig_0_16_or_later) {
+        // Zig 0.16: approximate with seconds precision
+        return @as(i128, time(null)) * 1_000_000_000;
+    } else {
+        // Zig 0.15 and earlier
+        return std.time.nanoTimestamp();
+    }
+}
+
+/// Create a fixed buffer stream compatible with both Zig 0.15 and 0.16
+/// Returns the appropriate FixedBufferStream type for the Zig version
+pub fn fixedBufferStream(buffer: []u8) FixedBufferStream {
+    if (comptime is_zig_0_16_or_later) {
+        // Zig 0.16: construct FixedBufferStream directly
+        return .{ .buffer = buffer, .pos = 0 };
+    } else {
+        // Zig 0.15 and earlier: use helper function
+        return std.io.fixedBufferStream(buffer);
+    }
+}
+
+/// Type alias for FixedBufferStream that works in both versions
+pub const FixedBufferStream = if (is_zig_0_16_or_later) blk: {
+    // Zig 0.16: Define our own FixedBufferStream with custom Writer
+    break :blk struct {
+        buffer: []u8,
+        pos: usize = 0,
+
+        const Self = @This();
+        
+        // Custom Writer implementation for Zig 0.16
+        pub const Writer = struct {
+            context: *Self,
+
+            pub fn writeAll(self: Writer, bytes: []const u8) error{NoSpaceLeft}!void {
+                const written = try self.context.write(bytes);
+                if (written != bytes.len) return error.NoSpaceLeft;
+            }
+
+            pub fn print(self: Writer, comptime format: []const u8, args: anytype) error{NoSpaceLeft}!void {
+                const context = self.context;
+                const remaining = context.buffer[context.pos..];
+                const written_slice = std.fmt.bufPrint(remaining, format, args) catch return error.NoSpaceLeft;
+                context.pos += written_slice.len;
+            }
+        };
+
+        pub fn writer(self: *Self) Writer {
+            return .{ .context = self };
+        }
+
+        fn write(self: *Self, bytes: []const u8) error{NoSpaceLeft}!usize {
+            if (self.pos + bytes.len > self.buffer.len) {
+                return error.NoSpaceLeft;
+            }
+            @memcpy(self.buffer[self.pos..][0..bytes.len], bytes);
+            self.pos += bytes.len;
+            return bytes.len;
+        }
+
+        pub fn getWritten(self: Self) []const u8 {
+            return self.buffer[0..self.pos];
+        }
+    };
+} else blk: {
+    // Zig 0.15: Use standard library type
+    break :blk @TypeOf(std.io.fixedBufferStream(@as([]u8, undefined)));
+};

examples/comprehensive/main.zig

@@ -2,6 +2,7 @@
 //! This example demonstrates multiple WebUI features working together
 const std = @import("std");
 const webui = @import("webui");
+const compat = @import("compat");
 
 const html = @embedFile("index.html");
 
@@ -148,7 +149,7 @@ fn getAppStatus(e: *webui.Event) void {
     var buffer: [1024]u8 = undefined;
     const json = std.fmt.bufPrintZ(buffer[0..],
         \\{{"status":"running","users":{},"messages":{},"files":{},"port":{},"url":"{s}","clientId":{},"timestamp":{}}}
-    , .{ app_state.users_online, app_state.messages_sent, app_state.files_uploaded, port, url, e.client_id, std.time.timestamp() }) catch "{\"error\":\"format_error\"}";
+    , .{ app_state.users_online, app_state.messages_sent, app_state.files_uploaded, port, url, e.client_id, compat.timestamp() }) catch "{\"error\":\"format_error\"}";
 
     std.debug.print("App Status - Users: {}, Messages: {}, Files: {}\n", .{ app_state.users_online, app_state.messages_sent, app_state.files_uploaded });
 
@@ -262,15 +263,15 @@ fn executeCommand(e: *webui.Event, command: [:0]const u8, args: [:0]const u8) vo
     if (std.mem.eql(u8, command, "echo")) {
         result = std.fmt.bufPrintZ(response[0..], "Echo: {s}", .{args}) catch "Error";
     } else if (std.mem.eql(u8, command, "time")) {
-        const timestamp = std.time.timestamp();
+        const timestamp = compat.timestamp();
         result = std.fmt.bufPrintZ(response[0..], "Current time: {}", .{timestamp}) catch "Error";
     } else if (std.mem.eql(u8, command, "random")) {
-        var prng = std.Random.DefaultPrng.init(@intCast(std.time.timestamp()));
+        var prng = std.Random.DefaultPrng.init(@intCast(compat.timestamp()));
         const random_num = prng.random().int(u32);
         result = std.fmt.bufPrintZ(response[0..], "Random number: {}", .{random_num}) catch "Error";
     } else if (std.mem.eql(u8, command, "memory")) {
         // Simple memory info (simulated)
-        result = std.fmt.bufPrintZ(response[0..], "Memory usage: {}MB", .{50 + @rem(std.time.timestamp(), 100)}) catch "Error";
+        result = std.fmt.bufPrintZ(response[0..], "Memory usage: {}MB", .{50 + @rem(compat.timestamp(), 100)}) catch "Error";
     } else {
         result = "Unknown command";
     }
@@ -282,15 +283,15 @@ fn getSystemInfo(e: *webui.Event) void {
     const builtin = @import("builtin");
 
     var buffer: [1024]u8 = undefined;
-    const info = std.fmt.bufPrintZ(buffer[0..],
+    const info = std.fmt.bufPrintZ(buffer[0..], 
         \\{{"os":"{s}","arch":"{s}","zigVersion":"{s}","webuiVersion":"2.5.0","timestamp":{}}}
-    , .{ @tagName(builtin.os.tag), @tagName(builtin.cpu.arch), @import("builtin").zig_version_string, std.time.timestamp() }) catch "{}";
+    , .{ @tagName(builtin.os.tag), @tagName(builtin.cpu.arch), @import("builtin").zig_version_string, compat.timestamp() }) catch "{}";
 
     e.returnString(info);
 }
 
 fn testPerformance(e: *webui.Event, iterations: i64, operation: [:0]const u8) void {
-    const start_time = std.time.nanoTimestamp();
+    const start_time = compat.nanoTimestamp();
 
     var i: i64 = 0;
     var result: u64 = 0;
@@ -306,7 +307,7 @@ fn testPerformance(e: *webui.Event, iterations: i64, operation: [:0]const u8) vo
         }
     }
 
-    const end_time = std.time.nanoTimestamp();
+    const end_time = compat.nanoTimestamp();
     const duration_ms = @as(f64, @floatFromInt(end_time - start_time)) / 1_000_000.0;
 
     var response: [256]u8 = undefined;

examples/event_handling/main.zig

@@ -3,6 +3,7 @@
 const std = @import("std");
 const webui = @import("webui");
 const builtin = @import("builtin");
+const compat = @import("compat");
 
 const html = @embedFile("index.html");
 
@@ -55,7 +56,7 @@ const UserContext = struct {
         context.* = UserContext{
             .user_id = user_id,
             .username = try allocator.dupe(u8, username),
-            .session_start = std.time.timestamp(),
+            .session_start = compat.timestamp(),
             .click_count = 0,
         };
         return context;
@@ -259,7 +260,7 @@ fn userLogout(e: *webui.Event) void {
     };
 
     // Calculate session duration
-    const session_duration = std.time.timestamp() - context.session_start;
+    const session_duration = compat.timestamp() - context.session_start;
 
     var response: [257]u8 = undefined; // +1 for null terminator
     const msg = std.fmt.bufPrint(response[0..256], 
@@ -324,7 +325,7 @@ fn getUserInfo(e: *webui.Event) void {
         return;
     };
 
-    const session_time = std.time.timestamp() - context.session_start;
+    const session_time = compat.timestamp() - context.session_start;
 
     var response: [513]u8 = undefined; // +1 for null terminator
     const json = std.fmt.bufPrint(response[0..512], 
@@ -371,7 +372,7 @@ fn broadcastUserListUpdate() void {
     var json_content: []const u8 = undefined;
 
     if (online_users) |users| {
-        var stream = std.io.fixedBufferStream(&users_json);
+        var stream = compat.fixedBufferStream(&users_json);
         var writer = stream.writer();
 
         writer.writeAll("[") catch return;
@@ -400,7 +401,7 @@ fn getOnlineUsers(e: *webui.Event) void {
     var json_content: []const u8 = undefined;
 
     if (online_users) |users| {
-        var stream = std.io.fixedBufferStream(&users_json);
+        var stream = compat.fixedBufferStream(&users_json);
         var writer = stream.writer();
 
         writer.writeAll("[") catch {

examples/js_execution/main.zig

@@ -2,6 +2,7 @@
 //! This example demonstrates running JavaScript from Zig and advanced communication
 const std = @import("std");
 const webui = @import("webui");
+const compat = @import("compat");
 
 const html = @embedFile("index.html");
 
@@ -133,7 +134,7 @@ fn sendDataToJs(e: *webui.Event, message: [:0]const u8, value: i64) void {
     var data: [256]u8 = undefined;
     const json_data = std.fmt.bufPrint(data[0..], 
         "{{\"message\":\"{s}\",\"value\":{},\"timestamp\":{}}}", 
-        .{message, value, std.time.timestamp()}) catch return;
+        .{message, value, compat.timestamp()}) catch return;
 
     // Send data to JavaScript function
     var js_call: [512]u8 = undefined;