CompileDaemon Documentation

CompileDaemon watches your .go files in a directory and invokes go build whenever a file changes.

Basic Usage

To run with default settings in the current working directory:

CompileDaemon

Run a command after a successful build

To automatically run your program (and restart it) every time it builds, use the -command flag:

CompileDaemon -command="./MyProgram -my-options"

Exclude directories and files

To prevent the daemon from watching specific directories (like .git) or files (like temporary editor files), use -exclude-dir and -exclude:

CompileDaemon -exclude-dir=.git -exclude=".#*"

Monitor specific file types

To include files other than the default .go and .c files, use the -include flag with glob patterns:

CompileDaemon -include=Makefile -include="*.less" -include="*.tmpl"

You can install CompileDaemon using the Go toolchain:

go install github.com/githubnemo/CompileDaemon@latest

CompileDaemon operates using a pipeline of watchers, builders, and runners:

1. Watcher: Monitors the filesystem for changes based on your -include, -exclude, and -pattern settings.
2. Builder: When a change is detected, it waits for the -work-delay (default 900ms) to pass (debouncing) before executing the -build commands. If the build fails, the process stops and does not trigger the runner.
3. Runner: If a -command is provided, the runner waits for a successful build. It then stops the currently running command (if any) and starts the new one.

If you use -command-stop, the runner will stop the previous command before the build starts, rather than waiting for the build to succeed.

CompileDaemon provides two distinct implementations of the FileWatcher interface to handle different environments and requirements:

NotifyWatcher (Native Notifications)

Uses fsnotify to leverage native operating system events. This is generally more efficient but may behave differently across OS platforms. It handles Remove, Write, and Create events. If a new directory is created, it is automatically added to the watch list if flagRecursive is enabled.

PollingWatcher (Polling-based)

Uses github.com/radovskyb/watcher to periodically check files for changes. This is useful in environments where native notifications are unreliable (e.g., certain Docker/Network mount setups). It uses flagPollingInterval to determine how often to check.

Changes on Docker volumes under Mac OS X may not be reported via standard FS notifications. To fix this, use the -polling flag to actively watch for changes:

CompileDaemon -polling

You can tune the frequency of checks using -polling-interval=N. Warning: Do not use polling in production as it is resource-intensive.

On OS X and BSD platforms, each watched file consumes a file descriptor. If you encounter this error:

1. Exclude VCS directories: Use -exclude-dir=… to ignore directories like .git or .hg.
2. Increase file limits: Use the ulimit command to raise your process's file limit (e.g., ulimit -n 1024). You may also need to adjust sysctl-based limits.

The WatcherConfig struct controls how files are discovered and which changes trigger events. Key fields include:

• flagPolling (bool): Enables polling-based watching instead of native OS notifications.
• flagRecursive (bool): If true, AddFiles() will walk through subdirectories.
• flagPollingInterval (int): The interval in milliseconds for polling-based watchers.
• flagDirectories (globList): The list of directories to watch.
• flagIncludedFiles (globList): Files that match these patterns will trigger events.
• flagExcludedFiles (globList): Files that match these patterns will be ignored.
• flagExcludedDirs (globList): Directories that will be skipped during recursive walks.
• flagVerbose (bool): If true, logs directory tracking or prints event info.