build: allow selecting a backend at comptime instead of via a build flag

build.zig

@@ -8,26 +8,12 @@ pub fn build(b: *std.Build) void {
         break :blk b.option(
             bool,
             "macos_fsevents",
-            "Use the FSEvents backend on macOS instead of kqueue (requires Xcode frameworks)",
+            "Add the FSEvents backend on macOS (requires Xcode frameworks)",
         ) orelse false;
     } else false;
 
-    const linux_read_thread = b.option(
-        bool,
-        "linux_read_thread",
-        "Use a background thread on Linux (like macOS/Windows) instead of requiring the caller to drive the event loop via poll_fd/handle_read_ready",
-    ) orelse true;
-
-    const kqueue_dir_only = b.option(
-        bool,
-        "kqueue_dir_only",
-        "Use directory-only kqueue watches (lower fd usage, no real-time file modification detection). Default: false",
-    ) orelse false;
-
     const options = b.addOptions();
     options.addOption(bool, "macos_fsevents", macos_fsevents);
-    options.addOption(bool, "linux_read_thread", linux_read_thread);
-    options.addOption(bool, "kqueue_dir_only", kqueue_dir_only);
     const options_mod = options.createModule();
 
     const mod = b.addModule("nightwatch", .{

src/backend/INotify.zig

@@ -1,12 +1,8 @@
 const std = @import("std");
-const build_options = @import("build_options");
 const types = @import("../types.zig");
-const Handler = types.Handler;
 const EventType = types.EventType;
 const ObjectType = types.ObjectType;
-
+const InterfaceType = types.InterfaceType;
-pub const watches_recursively = false;
-pub const detects_file_modifications = true;
 
 const PendingRename = struct {
     cookie: u32,
@@ -14,13 +10,28 @@ const PendingRename = struct {
     object_type: ObjectType,
 };
 
+pub fn Create(comptime variant: InterfaceType) type {
+    return struct {
         handler: *Handler,
         inotify_fd: std.posix.fd_t,
         watches: std.AutoHashMapUnmanaged(i32, []u8), // wd -> owned path
         pending_renames: std.ArrayListUnmanaged(PendingRename),
-// Used only in linux_read_thread mode:
+        stop_pipe: switch (variant) {
-stop_pipe: if (build_options.linux_read_thread) [2]std.posix.fd_t else void,
+            .threaded => [2]std.posix.fd_t,
-thread: if (build_options.linux_read_thread) ?std.Thread else void,
+            .polling => void,
+        },
+        thread: switch (variant) {
+            .threaded => ?std.Thread,
+            .polling => void,
+        },
+
+        pub const watches_recursively = false;
+        pub const detects_file_modifications = true;
+
+        const Handler = switch (variant) {
+            .threaded => types.Handler,
+            .polling => types.PollingHandler,
+        };
 
         const IN = std.os.linux.IN;
 
@@ -33,7 +44,8 @@ const in_flags: std.os.linux.O = .{ .NONBLOCK = true };
         pub fn init(handler: *Handler) !@This() {
             const inotify_fd = try std.posix.inotify_init1(@bitCast(in_flags));
             errdefer std.posix.close(inotify_fd);
-    if (comptime build_options.linux_read_thread) {
+            switch (variant) {
+                .threaded => {
                     const stop_pipe = try std.posix.pipe();
                     return .{
                         .handler = handler,
@@ -43,7 +55,8 @@ pub fn init(handler: *Handler) !@This() {
                         .stop_pipe = stop_pipe,
                         .thread = null,
                     };
-    } else {
+                },
+                .polling => {
                     return .{
                         .handler = handler,
                         .inotify_fd = inotify_fd,
@@ -52,11 +65,12 @@ pub fn init(handler: *Handler) !@This() {
                         .stop_pipe = {},
                         .thread = {},
                     };
+                },
             }
         }
 
         pub fn deinit(self: *@This(), allocator: std.mem.Allocator) void {
-    if (comptime build_options.linux_read_thread) {
+            if (comptime variant == .threaded) {
                 // Signal thread to stop and wait for it to exit.
                 _ = std.posix.write(self.stop_pipe[1], "x") catch {};
                 if (self.thread) |t| t.join();
@@ -72,15 +86,18 @@ pub fn deinit(self: *@This(), allocator: std.mem.Allocator) void {
         }
 
         pub fn arm(self: *@This(), allocator: std.mem.Allocator) error{HandlerFailed}!void {
-    if (comptime build_options.linux_read_thread) {
+            switch (variant) {
+                .threaded => {
                     if (self.thread != null) return; // already running
                     self.thread = std.Thread.spawn(.{}, thread_fn, .{ self, allocator }) catch return error.HandlerFailed;
-    } else {
+                },
+                .polling => {
                     return switch (self.handler.wait_readable() catch |e| switch (e) {
                         error.HandlerFailed => |e_| return e_,
                     }) {
                         .will_notify => {},
                     };
+                },
             }
         }
 
@@ -229,3 +246,5 @@ pub fn handle_read_ready(self: *@This(), allocator: std.mem.Allocator) (std.posi
                 }
             }
         }
+    };
+}

src/main.zig

@@ -3,8 +3,9 @@ const builtin = @import("builtin");
 const nightwatch = @import("nightwatch");
 
 const is_posix = switch (builtin.os.tag) {
-    .linux, .macos, .freebsd => true,
+    .linux, .macos, .freebsd, .openbsd, .netbsd, .dragonfly => true,
-    else => false,
+    .windows => false,
+    else => @compileError("unsupported OS"),
 };
 
 // Self-pipe: signal handler writes a byte so poll() / read() unblocks cleanly.
@@ -22,7 +23,6 @@ const CliHandler = struct {
     const vtable = nightwatch.Handler.VTable{
         .change = change_cb,
         .rename = rename_cb,
-        .wait_readable = if (nightwatch.linux_poll_mode) wait_readable_cb else {},
     };
 
     fn change_cb(h: *nightwatch.Handler, path: []const u8, event_type: nightwatch.EventType, object_type: nightwatch.ObjectType) error{HandlerFailed}!void {
@@ -215,7 +215,7 @@ pub fn main() !void {
         .ignore = ignore_list.items,
     };
 
-    var watcher = try nightwatch.init(allocator, &cli_handler.handler);
+    var watcher = try nightwatch.Default.init(allocator, &cli_handler.handler);
     defer watcher.deinit();
 
     for (watch_paths.items) |path| {

src/nightwatch.zig

@@ -7,25 +7,61 @@ pub const EventType = types.EventType;
 pub const ObjectType = types.ObjectType;
 pub const Error = types.Error;
 pub const ReadableStatus = types.ReadableStatus;
-pub const linux_poll_mode = types.linux_poll_mode;
+pub const InterfaceType = types.InterfaceType;
 pub const Handler = types.Handler;
+pub const PollingHandler = types.PollingHandler;
+
+pub const Variant = switch (builtin.os.tag) {
+    .linux => InterfaceType,
+    .macos => if (build_options.macos_fsevents) enum { fsevents, kqueue, kqueuedir } else enum { kqueue, kqueuedir },
+    .freebsd, .openbsd, .netbsd, .dragonfly => enum { kqueue, kqueuedir },
+    .windows => enum { windows },
+    else => @compileError("unsupported OS"),
+};
+
+pub const defaultVariant: Variant = switch (builtin.os.tag) {
+    .linux => .threaded,
+    .macos, .freebsd, .openbsd, .netbsd, .dragonfly => .kqueue,
+    .windows => .windows,
+    else => @compileError("unsupported OS"),
+};
+
+pub const Default: type = Create(defaultVariant);
+
+pub fn Create(comptime variant: Variant) type {
+    return struct {
+        pub const Backend = switch (builtin.os.tag) {
+            .linux => @import("backend/INotify.zig").Create(variant),
+            .macos => if (build_options.macos_fsevents) switch (variant) {
+                .fsevents => @import("backend/FSEvents.zig"),
+                .kqueue => @import("backend/KQueue.zig"),
+                .kqueuedir => @import("backend/KQueueDir.zig"),
+            } else switch (variant) {
+                .kqueue => @import("backend/KQueue.zig"),
+                .kqueuedir => @import("backend/KQueueDir.zig"),
+            },
+            .freebsd, .openbsd, .netbsd, .dragonfly => switch (variant) {
+                .kqueue => @import("backend/KQueue.zig"),
+                .kqueuedir => @import("backend/KQueueDir.zig"),
+            },
+            .windows => switch (variant) {
+                .windows => @import("backend/Windows.zig"),
+            },
+            else => @compileError("unsupported OS"),
+        };
+        pub const interfaceType: InterfaceType = switch (builtin.os.tag) {
+            .linux => variant,
+            else => .threaded,
+        };
+
+        allocator: std.mem.Allocator,
+        interceptor: *Interceptor,
 
         /// True if the current backend detects file content modifications in real time.
         /// False only when kqueue_dir_only=true, where directory-level watches are used
         /// and file writes do not trigger a directory NOTE_WRITE event.
         pub const detects_file_modifications = Backend.detects_file_modifications;
 
-const Backend = switch (builtin.os.tag) {
-    .linux => @import("backend/INotify.zig"),
-    .macos => if (build_options.macos_fsevents) @import("backend/FSEvents.zig") else if (build_options.kqueue_dir_only) @import("backend/KQueueDir.zig") else @import("backend/KQueue.zig"),
-    .freebsd, .openbsd, .netbsd, .dragonfly => if (build_options.kqueue_dir_only) @import("backend/KQueueDir.zig") else @import("backend/KQueue.zig"),
-    .windows => @import("backend/Windows.zig"),
-    else => @compileError("file_watcher: unsupported OS"),
-};
-
-allocator: std.mem.Allocator,
-interceptor: *Interceptor,
-
         pub fn init(allocator: std.mem.Allocator, handler: *Handler) !@This() {
             const ic = try allocator.create(Interceptor);
             errdefer allocator.destroy(ic);
@@ -76,7 +112,7 @@ pub fn unwatch(self: *@This(), path: []const u8) void {
         /// Drive event delivery by reading from the inotify fd.
         /// Only available in Linux poll mode (linux_poll_mode == true).
         pub fn handle_read_ready(self: *@This()) !void {
-    comptime if (!linux_poll_mode) @compileError("handle_read_ready is only available in Linux poll mode; use linux_read_thread=true for a background-thread model");
+            comptime if (@hasDecl(Backend, "polling") and Backend.polling) @compileError("handle_read_ready is only available in polling backends");
             try self.interceptor.backend.handle_read_ready(self.allocator);
         }
 
@@ -84,7 +120,7 @@ pub fn handle_read_ready(self: *@This()) !void {
         /// before calling handle_read_ready().
         /// Only available in Linux poll mode (linux_poll_mode == true).
         pub fn poll_fd(self: *const @This()) std.posix.fd_t {
-    comptime if (!linux_poll_mode) @compileError("poll_fd is only available in Linux poll mode; use linux_read_thread=true for a background-thread model");
+            comptime if (@hasDecl(Backend, "polling") and Backend.polling) @compileError("poll_fd is only available in polling backends");
             return self.interceptor.backend.inotify_fd;
         }
 
@@ -101,7 +137,38 @@ const Interceptor = struct {
             const vtable = Handler.VTable{
                 .change = change_cb,
                 .rename = rename_cb,
-        .wait_readable = if (linux_poll_mode) wait_readable_cb else {},
+            };
+
+            fn change_cb(h: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void {
+                const self: *Interceptor = @fieldParentPtr("handler", h);
+                if (event_type == .created and object_type == .dir and !Backend.watches_recursively) {
+                    self.backend.add_watch(self.allocator, path) catch {};
+                    recurse_watch(&self.backend, self.allocator, path);
+                }
+                return self.user_handler.change(path, event_type, object_type);
+            }
+
+            fn rename_cb(h: *Handler, src: []const u8, dst: []const u8, object_type: ObjectType) error{HandlerFailed}!void {
+                const self: *Interceptor = @fieldParentPtr("handler", h);
+                return self.user_handler.rename(src, dst, object_type);
+            }
+
+            fn wait_readable_cb(h: *Handler) error{HandlerFailed}!ReadableStatus {
+                const self: *Interceptor = @fieldParentPtr("handler", h);
+                return self.user_handler.wait_readable();
+            }
+        };
+
+        const PollingInterceptor = struct {
+            handler: PollingHandler,
+            user_handler: *PollingHandler,
+            allocator: std.mem.Allocator,
+            backend: Backend,
+
+            const vtable = PollingHandler.VTable{
+                .change = change_cb,
+                .rename = rename_cb,
+                .wait_readable = wait_readable_cb,
             };
 
             fn change_cb(h: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void {
@@ -137,3 +204,5 @@ fn recurse_watch(backend: *Backend, allocator: std.mem.Allocator, dir_path: []co
                 recurse_watch(backend, allocator, sub);
             }
         }
+    };
+}

src/nightwatch_test.zig

@@ -49,7 +49,6 @@ const TestHandler = struct {
     const vtable = nw.Handler.VTable{
         .change = change_cb,
         .rename = rename_cb,
-        .wait_readable = if (nw.linux_poll_mode) wait_readable_cb else {},
     };
 
     fn change_cb(handler: *nw.Handler, path: []const u8, event_type: nw.EventType, object_type: nw.ObjectType) error{HandlerFailed}!void {
@@ -135,7 +134,7 @@ const TestHandler = struct {
 // ---------------------------------------------------------------------------
 // Watcher type alias - nightwatch.zig is itself a struct type.
 // ---------------------------------------------------------------------------
-const Watcher = nw;
+const Watcher = nw.Default;
 
 // ---------------------------------------------------------------------------
 // Test utilities
@@ -178,13 +177,12 @@ fn removeTempDir(path: []const u8) void {
 }
 
 /// Drive event delivery:
-///  - Linux:   call handle_read_ready() so inotify events are processed.
+///  - polling watchers: call handle_read_ready() so events are processed.
-///  - Others:  the backend uses its own thread/callback; sleep briefly.
+///  - threaded watchers: the backend uses its own thread/callback; sleep briefly.
 fn drainEvents(watcher: *Watcher) !void {
-    if (nw.linux_poll_mode) {
+    switch (Watcher.interfaceType) {
-        try watcher.handle_read_ready();
+        .polling => try watcher.handle_read_ready(),
-    } else {
+        .threaded => std.Thread.sleep(300 * std.time.ns_per_ms),
-        std.Thread.sleep(300 * std.time.ns_per_ms);
     }
 }
 
@@ -223,7 +221,7 @@ test "creating a file emits a 'created' event" {
 test "writing to a file emits a 'modified' event" {
     // kqueue watches directories only; file writes don't trigger a directory event,
     // so modifications are not reliably detectable in real time on this backend.
-    if (comptime !nw.detects_file_modifications) return error.SkipZigTest;
+    if (comptime !Watcher.detects_file_modifications) return error.SkipZigTest;
 
     const allocator = std.testing.allocator;
 
@@ -516,7 +514,7 @@ test "rename-then-modify: rename event precedes the subsequent modify event" {
     // After renaming a file, a write to the new name should produce events in
     // the order [rename/old-name, rename/new-name, modify] so that a consumer
     // always knows the current identity of the file before seeing changes to it.
-    if (comptime !nw.detects_file_modifications) return error.SkipZigTest;
+    if (comptime !Watcher.detects_file_modifications) return error.SkipZigTest;
 
     const allocator = std.testing.allocator;
 

src/types.zig

@@ -1,6 +1,5 @@
 const std = @import("std");
 const builtin = @import("builtin");
-const build_options = @import("build_options");
 
 pub const EventType = enum {
     created,
@@ -25,14 +24,9 @@ pub const Error = error{
     WatchFailed,
 };
 
-/// True when the Linux inotify backend runs in poll mode (caller drives the
+pub const InterfaceType = enum {
-/// event loop via poll_fd / handle_read_ready).  False on all other platforms
+    polling,
-/// and on Linux when the `linux_read_thread` build option is set.
+    threaded,
-pub const linux_poll_mode = builtin.os.tag == .linux and !build_options.linux_read_thread;
-
-pub const ReadableStatus = enum {
-    // TODO: is_readable, // backend may now read from fd (blocking mode)
-    will_notify, // backend must wait for a handle_read_ready call
 };
 
 pub const Handler = struct {
@@ -41,8 +35,31 @@ pub const Handler = struct {
     pub const VTable = struct {
         change: *const fn (handler: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void,
         rename: *const fn (handler: *Handler, src_path: []const u8, dst_path: []const u8, object_type: ObjectType) error{HandlerFailed}!void,
-        /// Only present in Linux poll mode (linux_poll_mode == true).
+    };
-        wait_readable: if (linux_poll_mode) *const fn (handler: *Handler) error{HandlerFailed}!ReadableStatus else void,
+
+    pub fn change(handler: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void {
+        return handler.vtable.change(handler, path, event_type, object_type);
+    }
+
+    pub fn rename(handler: *Handler, src_path: []const u8, dst_path: []const u8, object_type: ObjectType) error{HandlerFailed}!void {
+        return handler.vtable.rename(handler, src_path, dst_path, object_type);
+    }
+};
+
+/// Used only by the inotify backend in poll mode (caller drives the event
+/// loop via poll_fd / handle_read_ready)
+pub const PollingHandler = struct {
+    vtable: *const VTable,
+
+    pub const ReadableStatus = enum {
+        // TODO: is_readable, // backend may now read from fd (blocking mode)
+        will_notify, // backend must wait for a handle_read_ready call
+    };
+
+    pub const VTable = struct {
+        change: *const fn (handler: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void,
+        rename: *const fn (handler: *Handler, src_path: []const u8, dst_path: []const u8, object_type: ObjectType) error{HandlerFailed}!void,
+        wait_readable: *const fn (handler: *Handler) error{HandlerFailed}!ReadableStatus,
     };
 
     pub fn change(handler: *Handler, path: []const u8, event_type: EventType, object_type: ObjectType) error{HandlerFailed}!void {
@@ -54,10 +71,6 @@ pub const Handler = struct {
     }
 
     pub fn wait_readable(handler: *Handler) error{HandlerFailed}!ReadableStatus {
-        if (comptime linux_poll_mode) {
         return handler.vtable.wait_readable(handler);
-        } else {
-            unreachable;
-        }
     }
 };