Permalink
Fetching contributors…
Cannot retrieve contributors at this time
65 lines (56 sloc) 3.22 KB

Close Watch

This is an sbt plugin that aims to lower the latency between file system events and sbt tasks. It replaces the default watch service with a more highly optimized service that works well on all platforms.

Usage

Add

addSbtPlugin("com.swoval" %% "sbt-close-watch" % "2.0.4")

to your project/plugins.sbt. To apply the plugin globally, add those commands to ~/.sbt/1.0/plugins/watch.sbt or ~/.sbt/0.13/plugins/watch.sbt (creating the file if necessary).

The plugin can be configured with the following options:

  • closeWatchAntiEntropy (default 35 milliseconds) -- Controls the anti-entropy parameter of the updated ~ command. Some programs touch a file a few times on save and this paramter prevent spurious builds if the same file is touched multiple times within this period.
  • closeWatchFileCache -- Controls the file cache used by the plugin to list source files. If there is a problem with the source files generated by the plugin, set closeWatchFileCache := com.swoval.files.FileTreeRepositories.NoCache
  • closeWatchLegacyWatchLatency (sbt 1.x only) -- If using the default sbt WatchService, configures the latency of the directory watcher.
  • closeWatchLegacyQueueSize (sbt 1.x only) -- If using the default sbt WatchService, configures the maximum number of watch events that will be enqueued.
  • closeWatchUseDefaultWatchService (default: false, sbt 1.x only) -- Use the default sbt watch service with the MacOSXWatchService. This doesn't benefit from a number of the enhancements that the plugin makes to the ~ command, but it does make the basic watch service usable on OSX.

Debugging

There are two tasks provided for debugging

  • closeWatchTransitiveSources -- This shows the list of sources that the plugin is using for a particular task. Usage: foo/closeWatchTransitiveSources foo/compile will show the watch sources used in the foo/compile task. Note that this can be very noisy if foo is an aggregate project.
  • closeWatchSourceDiff -- Shows the difference, if any, between the compilation sources generated by the default sbt source generators compared to the compilation sources generated by the plugin.

If your build overrides the onLoad or onUnload tasks without delegating to the previous definitions of onLoad or unLoad, then the plugin may not work correctly and you may see errors like:

[error] java.lang.IllegalStateException: Global file repository was not previously registered
[error] 	at com.swoval.watchservice.CloseWatchPlugin$.$anonfun$globalSettings$2(CloseWatchPlugin.scala:250)
[error] 	at scala.Option.getOrElse(Option.scala:121)
[error] 	at com.swoval.watchservice.CloseWatchPlugin$.$anonfun$globalSettings$1(CloseWatchPlugin.scala:250)

To fix this, you can just update your build definition to be

 onLoad := { state =>
  onLoad.value(state)
  ... // your custom onLoad logic
 }

Credits

The initial implementation was based on directory-watcher, which in turn relied on takari-directory-watcher. Thanks to @francisdb who provided lots of early feedback.

License

This library is licensed under the MIT license. See LICENSE for more information.