Build Runner: Implement File System Watching for kqueue

[andrewrk]

Extracted from #20580.

Most of the file system watching mechanism is abstracted across operating systems, however, the parts that deal with receiving events from file system changes require OS-specific implementations.

zig/lib/std/Build/Watch.zig

Line 324 in 1d20ff1

else => @compileError("unimplemented"),

This issue is for the kqueue implementation, which covers most of the BSDs, including macOS.

Related:

• Build Runner: Implement File System Watching on Windows #20598

[tiehuis]

Based on some initial reading, kqueue requires a fd for each file being watched and not simply on the parent directory fd like can be done with inotify, which will cause issues if many files need to be watched individually.

An alternative for Mac is to use FSEvents which looks to be suitable for the workflow. I am not sure if this included by default in the core libraries available to use from zig.

[andrewrk]

I heard from @Jarred-Sumner today that you can dlopen frameworks such as FSEvents. That might be an option to explore. It's not really a good solution though because we want something that works for all the BSDs.

I'll double check the kqueue API too. We really need directory events, it's not really possible to implement correct behavior by only watching files. I bet it's possible.

[ghostiam]

I found the implementation on kqueue.
Think this can help us in implementation.
freebsd || openbsd || netbsd || dragonfly || darwin
https://github.com/fsnotify/fsnotify/blob/main/backend_kqueue.go

[andrewrk]

Based on that Go code, kqueue indeed allows watching directories, however those events do not provide the names of changed files within the watched directory.

https://github.com/fsnotify/fsnotify/blob/c1467c02fba575afdb5f4201072ab8403bbf00f4/backend_kqueue.go#L524-L525

This is fine for our purposes here. It will just trigger a rebuild if any files are changed when any sibling files are watched. The Go code noted above simulates file system watching by scanning watched directories when their events fire. The Zig code will not need that hack since the rebuild will already do such a scan.

This is a pretty straightforward patch.