How do filenames like watcher_linux.go and watcher_darwin.go keep per-platform syscall code compiling on every GOOS?

## The rule Before compiling a package, the go command decides which files belong to it for the current target. Part of that decision comes from the filename alone. If a file's base name, after stripping `.go` and any `_test` suffix, ends in: - `_GOOS` — `watcher_linux.go`, `watcher_darwin.go`, `watcher_windows.go` - `_GOARCH` — `layout_amd64.go`, `layout_arm64.go` - `_GOOS_GOARCH` — `watcher_linux_amd64.go` then the file is compiled only when the target matches. No directive is written inside it. Test files follow the same rule, so `watcher_linux_test.go` runs only on Linux. Two details cause real confusion: 1. **The suffix must follow an underscore, after a non-empty base name.** A file named `linux.go` has no constraint at all and is compiled on every platform — a classic mistake that produces a package that only builds on the author's machine. A file named `_linux.go` is worse: the go command ignores files whose names begin with `_` or `.` entirely, so the code silently disappears from the build everywhere. 2. **Only real GOOS and GOARCH values are recognised.** `watcher_unix.go` is not special — `unix` is not a GOOS — so that file compiles everywhere. Grouping several Unix platforms into one file needs an explicit build constraint line, which is a separate mechanism from this naming convention. ## The pattern it enables The convention exists so platform differences stay at the leaves. Declare one unexported entry point per platform: ```go // watcher_linux.go func newWatcher(root string) (*watcher, error) { return startInotify(root) } // watcher_darwin.go func newWatcher(root string) (*watcher, error) { return startKqueue(root) } ``` Everything else in the package — the indexer loop, the queue, the tests for path handling — calls `newWatcher` and never mentions a platform. The compiler sees exactly one definition per build, so there is no duplicate-symbol problem and no runtime dispatch. Keep the *signature* identical across the files. Since only one is ever compiled, a drifted signature in the file you do not build locally is invisible until someone builds that target. ## The failure mode this creates Omit a platform and the package does not fail gracefully — it fails to compile there, with `undefined: newWatcher`. That is arguably the right outcome, because it is loud, but it is loud *for whoever builds that target*, which may be a user rather than you. So make the support matrix explicit. For platforms you intend to support, write the file and build it in CI. For the rest, provide a fallback file, constrained to "everything else", whose `newWatcher` returns an error saying the platform is unsupported. `errors.ErrUnsupported` is the idiomatic sentinel to wrap, so callers can test the condition rather than the message. ## Why CI has to cross-compile On your machine, `go build ./...` and `go vet ./...` examine one GOOS and one GOARCH. Every other platform file is invisible: not compiled, not type-checked, not vetted. Editors behave the same way. A syntax error, a wrong signature or a constant that does not exist on that platform sits undetected until someone builds it. The cheap defence is a build-only matrix in CI: ``` GOOS=linux GOARCH=amd64 go build ./... GOOS=linux GOARCH=arm64 go build ./... GOOS=darwin GOARCH=arm64 go build ./... ``` Cross-compiling pure Go needs no extra toolchain, so this costs seconds and catches the whole class. Running the *tests* on each platform is a much bigger commitment, and the difference between "we compile for it" and "we test on it" is worth stating in the README rather than leaving to inference. ## Where it fits with the rest of the mechanism The filename convention is a shorthand for the general build-constraint system. Anything the naming cannot express — a group of Unix platforms, a custom tag, a Go-version condition — needs an explicit constraint line at the top of the file. Use the filename where it fits, because it is impossible to get out of sync with the file's contents, and reserve explicit constraints for the cases that genuinely need an expression.