Watch コマンド

概要

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

説明

Watch コマンドは ~ (チルダ) で表し、特定タスクの入力ファイルを監視し、ファイルに変更が発生したときにタスクを再実行する機能を提供する。

以下に使用例を用いて解説する:

コンパイル

一般的な用途は継続的コンパイルである。以下のコマンドはそれぞれ 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 はタスクを評価する前、またはイベントがトリガーされた後にコンソール画面をクリアできる。イベントトリガー後に画面をクリアするには、以下を追加する:

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' キーでビルドがリロードされ、改行でシェルに戻る。デフォルトでは 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 である。

The Book of sbt