Watch 命令

概要

sbt ~ command1
sbt ~ command1 [ ; command2 ; ... ]

描述

Watch 命令以 ~（波浪号）表示，可监控特定任务的输入文件，并在这些文件发生变更时重复执行任务。

以下描述了一些示例用法：

编译

常见用途是持续编译。以下命令将分别让 sbt 监控 Test 和 Compile（默认）配置中的源变更，并重新运行 compile 命令。

> ~ Test / compile

> ~ compile

注意，由于 Test / compile 依赖 Compile / compile，主源目录中的源变更将触发测试源的重新编译。

测试

触发式执行常用于测试驱动开发（TDD）风格。以下命令将监控构建的主源和测试源变更，并仅重新运行引用自上次测试运行以来已重新编译的类的测试。

> ~ test

若某测试的依赖已变更，也可仅重新运行该测试。

> ~ test foo.BarTest

可配置为在检测到源变更时始终重新运行某测试，无论该测试是否依赖任何已更新的源文件。

> ~ testOnly foo.BarTest

要在任何源变更时运行项目中所有测试，请使用

> ~ testFull

运行多个命令

Watch 命令支持监控多个以分号分隔的任务。例如，以下命令将监控源文件变更并运行 clean 和 test：

> ~ clean; test

构建源

若通过设置 Global / onChangedBuildSource := ReloadOnSourceChanges 将构建配置为在构建源变更时自动重新加载，则 sbt 将监控构建源（即 project 目录中的 *.sbt 和 *.{java,scala} 文件）。检测到构建源变更时，构建将重新加载，重新加载完成后 sbt 将重新进入触发式执行模式。

清屏

sbt 可在评估任务前或触发事件后清空控制台屏幕。要配置 sbt 在事件触发后清屏，请添加

ThisBuild / watchTriggeredMessage := Watch.clearScreenOnTrigger

到构建设置中。要在运行任务前清屏，请添加

ThisBuild  / watchBeforeCommand := Watch.clearScreen

到构建设置中。

配置

触发式执行的行为可通过若干设置进行配置。

  • watchTriggers: Seq[Glob] 为应触发任务评估但任务不直接依赖的文件添加搜索查询。例如，若项目 build.sbt 包含 foo / watchTriggers += baseDirectory.value.toGlob / "*.txt"，则对以 txt 扩展名结尾的文件的任何修改都会在触发式执行模式下触发 foo 命令。

  • watchTriggeredMessage: (Int, Path, Seq[String]) => Option[String] 设置文件修改触发新构建时显示的消息。其输入参数为当前 watch 迭代次数、触发构建的文件以及将要运行的命令。默认打印指示哪个文件触发构建以及将运行哪些命令的消息。函数返回 None 时不打印消息。要在打印消息前清屏，在任务定义中添加 Watch.clearScreen() 即可。这将确保先清屏，再打印（若有定义的）消息。

  • watchInputOptions: Seq[Watch.InputOption] 允许构建覆盖默认 watch 选项。例如，要添加通过按 'l' 键重新加载构建的能力，在 build.sbt 中添加 ThisBuild / watchInputOptions += Watch.InputOption('l', "reload", Watch.Reload)。使用默认 watchStartMessage 时，这也会将该选项添加到 '?' 选项显示的列表中。

  • watchBeforeCommand: () => Unit 提供在评估任务前运行的回调。可通过在项目 build.sbt 中添加 ThisBuild / watchBeforeCommand := Watch.clearScreen 来清空控制台屏幕。默认为空操作。

  • watchLogLevel 设置文件监控系统的日志级别。当源文件被修改时触发式执行未评估，或因对不应监控的文件的修改而意外触发时，此设置很有用。

  • watchInputParser: Parser[Watch.Action] 更改监控器处理输入事件的方式。例如，设置 watchInputParser := 'l' ^^^ Watch.Reload | '\r' ^^^ new Watch.Run("") 将使按 'l' 键重新加载构建，按换行键返回 shell。默认从 watchInputOptions 自动派生。

  • watchStartMessage: (Int, ProjectRef, Seq[String]) => Option[String] 设置 watch 进程等待文件或输入事件时打印的横幅。输入为迭代次数、当前项目和要运行的命令。默认消息包含终止 watch 或显示所有可用选项的说明。仅当 watchOnIteration 记录 watchStartMessage 结果时才显示此横幅。

  • watchOnIteration: (Int, ProjectRef, Seq[String]) => Watch.Action 在等待源或输入事件前评估的函数。例如，若达到一定迭代次数，可用于提前终止 watch。默认仅记录 watchStartMessage 的结果。

  • watchForceTriggerOnAnyChange: Boolean 配置源文件内容是否必须变更才能触发构建。默认值为 false。

  • watchPersistFileStamps: Boolean 切换 sbt 是否在多次任务评估运行间持久化为源文件计算的文件哈希。这可提高具有大量源文件的项目的性能。由于文件哈希被缓存，若多个源文件被并发修改，评估的任务可能读取到无效哈希。默认值为 false。

  • watchAntiEntropy: FiniteDuration 控制同一文件在先前触发构建后，必须经过多长时间才能再次触发构建。用于防止文件在短时间内多次修改时产生虚假构建。默认值为 500ms。