Draft: Implement watching file paths via oslib.watch (#5068)

Currently watching files uses polling which is inefficient with large
codebases. On my laptop `./mill --watch` uses 20% CPU just to watch the
files for changes.

This uses `oslib`'s `watch` module to watch for the file changes instead
of polling them.

We had to update oslib (com-lihaoyi/os-lib#386)
to:
- add a capability of filtering what folders it watches. This is needed
because watching large generated folders like `out` or `.bloop` emits
Java FS watcher `OVERFLOW` events.
- remove the random `println`'s that `oslib.watch` had.

The current approach to watching is to watch the workspace root via FS
watching. FS watching only works with folders and we have to watch
`root/build.mill`, and thus, `root/`, so everything else falls under it.

Mac OS watcher performs watching recursively natively, but on linux
oslib adds recursive watches itself, so we use `oslib.watch` filter to
prevent watching anything that is not an ancestor of watched root. For
example, if we have source at `root/module-a/src/`, we'll watch `root/`,
`root/module-a/` and `root/`.

Finally, events are filtered so that unrelated changes (like creating
`root/random-file.txt`) does not trigger reevaluation.

The fs watching is enabled by default and can be disabled via
`--watch-via-fs-notify=false`.

`0.12.x` version: #5073

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: arturaz

core/api/src/mill/api/Watchable.scala

@@ -8,6 +8,22 @@ package mill.api
  */
 private[mill] sealed trait Watchable
 private[mill] object Watchable {
+
+  /**
+   * Watched path, can be watched via polling or via a notification system.
+   *
+   * @param p the path to watch
+   * @param quick if true, only watch file attributes
+   * @param signature the initial hash of the path contents
+   */
   case class Path(p: java.nio.file.Path, quick: Boolean, signature: Int) extends Watchable
+
+  /**
+   * Watched expression, can only be watched via polling.
+   *
+   * @param f the expression to watch, returns some sort of hash
+   * @param signature the initial hash from the first invocation of the expression
+   * @param pretty human-readable name
+   */
   case class Value(f: () => Long, signature: Long, pretty: String) extends Watchable
 }

integration/invalidation/watch-source-input/src/WatchSourceInputTests.scala

@@ -44,12 +44,9 @@ trait WatchTests extends UtestIntegrationTestSuite {
     val expectedShows0 = mutable.Buffer.empty[String]
     val res = f(expectedOut, expectedErr, expectedShows0)
     val (shows, out) = res.out.linesIterator.toVector.partition(_.startsWith("\""))
-    val err = res.err.linesIterator.toVector
-      .filter(!_.contains("Compiling compiler interface..."))
-      .filter(!_.contains("Watching for changes"))
-      .filter(!_.contains("[info] compiling"))
-      .filter(!_.contains("[info] done compiling"))
-      .filter(!_.contains("mill-daemon/ exitCode file not found"))
+    val err = res.err.linesIterator.toVector.filter(s =>
+      s.startsWith("Setting up ") || s.startsWith("Running ")
+    )
 
     assert(out == expectedOut)
 

mill-build/src/millbuild/Deps.scala

@@ -117,7 +117,9 @@ object Deps {
   val junitInterface = mvn"com.github.sbt:junit-interface:0.13.3"
   val commonsIo = mvn"commons-io:commons-io:2.18.0"
   val log4j2Core = mvn"org.apache.logging.log4j:log4j-core:2.24.3"
-  val osLib = mvn"com.lihaoyi::os-lib:0.11.5-M8"
+  val osLibVersion = "0.11.5-M8"
+  val osLib = mvn"com.lihaoyi::os-lib:$osLibVersion"
+  val osLibWatch = mvn"com.lihaoyi::os-lib-watch:$osLibVersion"
   val pprint = mvn"com.lihaoyi::pprint:0.9.0"
   val mainargs = mvn"com.lihaoyi::mainargs:0.7.6"
   val millModuledefsVersion = "0.11.4"

runner/daemon/package.mill

@@ -19,6 +19,7 @@ object `package` extends MillPublishScalaModule {
   def mvnDeps = Seq(
     Deps.sourcecode,
     Deps.osLib,
+    Deps.osLibWatch,
     Deps.mainargs,
     Deps.upickle,
     Deps.pprint,

runner/daemon/src/mill/daemon/MillBuildBootstrap.scala

@@ -275,7 +275,7 @@ class MillBuildBootstrap(
         // look at the `moduleWatched` of one frame up (`prevOuterFrameOpt`),
         // and not the `moduleWatched` from the current frame (`prevFrameOpt`)
         val moduleWatchChanged =
-          prevOuterFrameOpt.exists(_.moduleWatched.exists(w => !Watching.validate(w)))
+          prevOuterFrameOpt.exists(_.moduleWatched.exists(w => !Watching.haveNotChanged(w)))
 
         val classLoader = if (runClasspathChanged || moduleWatchChanged) {
           // Make sure we close the old classloader every time we create a new

runner/daemon/src/mill/daemon/MillCliConfig.scala

@@ -102,6 +102,11 @@ case class MillCliConfig(
       doc = """Watch and re-run the given tasks when when their inputs change."""
     )
     watch: Flag = Flag(),
+    @arg(
+      name = "notify-watch",
+      doc = "Use filesystem based file watching instead of polling based one (defaults to true)."
+    )
+    watchViaFsNotify: Boolean = true,
     @arg(
       short = 's',
       doc =

runner/daemon/src/mill/daemon/MillMain.scala

@@ -4,21 +4,21 @@ import mill.api.internal.{BspServerResult, internal}
 import mill.api.{Logger, MillException, Result, SystemStreams}
 import mill.bsp.BSP
 import mill.client.lock.Lock
-import mill.constants.{OutFiles, DaemonFiles, Util}
-import mill.{api, define}
+import mill.constants.{DaemonFiles, OutFiles, Util}
 import mill.define.BuildCtx
 import mill.internal.{Colors, MultiStream, PromptLogger}
 import mill.server.Server
 import mill.util.BuildInfo
+import mill.{api, define}
 
 import java.io.{InputStream, PipedInputStream, PrintStream}
 import java.lang.reflect.InvocationTargetException
 import java.util.Locale
 import java.util.concurrent.locks.ReentrantLock
 import scala.collection.immutable
 import scala.jdk.CollectionConverters.*
-import scala.util.{Properties, Using}
 import scala.util.control.NonFatal
+import scala.util.{Properties, Using}
 
 @internal
 object MillMain {
@@ -344,9 +344,13 @@ object MillMain {
                       if (config.watch.value) os.remove(out / OutFiles.millSelectiveExecution)
                       Watching.watchLoop(
                         ringBell = config.ringBell.value,
-                        watch = config.watch.value,
+                        watch = Option.when(config.watch.value)(Watching.WatchArgs(
+                          setIdle = setIdle,
+                          colors,
+                          useNotify = config.watchViaFsNotify,
+                          daemonDir = daemonDir
+                        )),
                         streams = streams,
-                        setIdle = setIdle,
                         evaluate = (enterKeyPressed: Boolean, prevState: Option[RunnerState]) => {
                           adjustJvmProperties(userSpecifiedProperties, initialSystemProperties)
                           runMillBootstrap(
@@ -356,8 +360,7 @@ object MillMain {
                             streams,
                             config.leftoverArgs.value.mkString(" ")
                           )
-                        },
-                        colors = colors
+                        }
                       )
                     }
                   }