sbt

基本的な導入としては、sbt 入門ガイドの基本タスクをまず読んでみてほしい。

概要

sbt
sbt コマンド 引数
sbt --server
sbt --script-version

説明

sbt は最初は Scala と Java のために作られたシンプルなビルド・ツールだ。sbt はサブプロジェクト、様々な依存性、カスタムタスクなどを宣言することで高速かつ再現性の高いビルドが得られることを保証する。

sbt runner と sbt server

sbt runner は sbt という名前のシステム・シェル・スクリプトで、Windows では sbt.bat と呼ばれる。これは、どのバージョンの sbt でも実行することが可能で、これは「sbt という名前のシェル・スクリプト」とも呼ばれる。
- sbt 2.x が検知されると、sbt runner は、典型的には GraalVM ネイティブで実装されたクライアント・プログラムである sbtn を用いて、クライアント・モードで実行する。
- sbt runner は sbt ランチャーという、全てのバージョンの sbt を起動できるランチャーを実行する。
- sbt をインストールした場合、インストールされるのは sbt runner だ。
sbt server は、sbt の本体で、実際のビルドツールだ。
- sbt のバージョンは、それぞれのワーキング・ディレクトリ内にある project/build.properties によって決定される。
- sbt server は、sbtn、ネットワーク API、もしくは独自の sbt シェルのいずれかからコマンドを受け取る。

sbt.version=2.0.0-RC9

この機構によってビルドを特定のバージョンの sbt に設置することができ、プロジェクトで作業する人全員が、マシンにインストールされた sbt runner に関わらず同一のビルド意味論を共有できるようになる。

このような分割があるため、機能の一部は sbt runner や sbtn のレベルで実装され、その他の機能は sbt server レベルで実装される。

sbt コマンド

コマンドに関する備考

sbt には、サブプロジェクトのレベルで動作するタスク (compile など) とビルド定義そのものを操作することも可能な狭義のコマンド (set など) がある。

しかし、act コマンドによってセッティングやタスクもコマンドに持ち上げることが可能なため「sbt シェルに打ち込むことができるもの全て」を広義のコマンドとしても解釈できる。詳細はコマンドのコンセプトのページを参照。

サブプロジェクト・レベルのタスク

clean 生成されたファイル (target ディレクトリ) を削除する。
publish publishTo セッティングで指定されたリポジトリにJAR ファイルなどのアーティファクトを公開する。
publishLocal JAR ファイルなどのアーティファクトをローカルの Ivy リポジトリに公開する。
update ライブラリ依存性の解決と取得を行う。

コンフィギュレーション・レベルのタスクは、コンフィギュレーションに関連付けされたタスクだ。例えば、compile は Compile/compile と等価であり、(Compile コンフィギュレーションで管理される) main のソースコードをコンパイルする。Test/compile は (Test コンフィギュレーションで管理される) テストのソースコードをコンパイルする。Compile コンフィギュレーションのほとんどのタスクはTest コンフィギュレーション内に対応するものがあり、Test/ とプレフィックスを付けることで実行できる。

compile (src/main/scala ディレクトリの中の) main のソースをコンパイルする。Test/compile は、 (src/test/scala ディレクトリの中の) テストのソースをコンパイルする。
console コンパイルされたソース、lib ディレクトリ内の全ての JAR、マネージ依存性を含んだクラスパスを用いて Scala インタプリタを起動する。sbt へ戻るには、:quit、Ctrl+D (Unix)、もしくは Ctrl+Z (Windows) と打ち込む。同様に、Test/console はテストクラスとクラスパスを用いてインタプリタを起動する。
doc scaladoc を用いて src/main/scala/ 内の Scala ソースの API ドキュメンテーションを生成する。Test/doc は、src/test/scala 内のソースファイルのための API ドキュメンテーションを生成する。
package src/main/resources 内のファイルと src/main/scala からコンパイルされたクラスを含む JAR ファイルを作成する。Test/package は、src/test/resources 内のファイルと src/test/scala からコンパイルされたクラスを含む JAR ファイルを作成する。
packageDoc src/main/scala 内の Scala ソースより生成された API ドキュメンテーションを含む JAR ファイルを作成する。Test/packageDoc は、src/test/scala 内のテスト・ソースより生成された API ドキュメンテーションを含む JAR ファイルを作成する。
packageSrc 全ての main のソースファイルとリソースを含む JAR ファイルを作成する。パッケージは src/main/scala および src/main/resources からの相対パスとなる。同様に、Test/packageSrc はテストソースとリソースをパッケージ化する。
run <引数>* サブプロジェクトのメインクラスを sbt と同じ JVM 上から実行する。引数はそのままメインクラスに渡される。
runMain <メインクラス> <引数>* サブプロジェクトから指定されたメインクラスを sbt と同じ JVM 上から実行する。引数はそのままメインクラスに渡される。
test <test>* Runs the tests specified as arguments (or all tests if no arguments are given) that:
1. 未だ実行されていない、もしくは
2. 前回実行されたときに失敗した、もしくは
3. 前に成功してから間接依存ライブラリのいずれかが再コンパイルされた
  * は、テスト名のワイルドカードとして解釈される。
testFull テストのコンパイル時に検知された全てのテストを実行する。

一般コマンド

shutdown sbt server をシャットダウンして現行の sbt セッションを終了する。
exit または quit 現行の sbt セッションまたはビルドを終了する。また、Ctrl+D (Unix) または Ctrl+Z (Windows) でもシェルを終了できる。
help <command> 渡されたコマンドの詳細なヘルプを表示する。コマンドが存在しない場合、引数（正規表現として解釈される）に名前または説明が一致するコマンドの詳細ヘルプを一覧表示する。引数が指定されていない場合、主要なコマンドの簡潔な説明を表示する。関連コマンド: tasks、settings
projects [add|remove <URI>] 引数が指定されていない場合は利用可能なプロジェクトを一覧表示し、指定された URI のビルドを追加または削除する。

Watch コマンド ~ <command> ソースファイルが変更されるたびに指定されたアクションを実行する。
< filename 指定されたファイル内のコマンドを実行する。各コマンドは1行ずつ記述する。空行と '#' で始まる行は無視される。
A ; B A を実行し、成功したら B を実行する。先頭のセミコロンが必要であることに注意。
eval <Scala-expression> 渡された Scala 式を評価し、結果と推論された型を返す。システムプロパティの設定、電卓としての使用、プロセスのフォークなどに使用できる。例:
```
> eval System.setProperty("demo", "true")
> eval 1+1
> eval "ls -l" !
```

ビルド定義を管理するコマンド

reload [plugins|return] 引数が指定されていない場合、ビルドをリロードし、必要に応じてビルド定義やプラグイン定義を再コンパイルする。reload plugins はカレント・プロジェクトをメタビルドプロジェクト (project/ 内) に切り替える。ビルド定義を直接操作するのに便利である。例えば、ビルド定義プロジェクトで clean を実行すると、スナップショットの更新とビルド定義の再コンパイルが強制される。reload return はメインプロジェクトに戻る。
set <setting-expression> 渡されたセッティング定義を評価して適用する。セッティングは sbt が再起動されるか、ビルドがリロードされるか、別の set コマンドで上書きされるか、session コマンドで削除されるまで有効である。
session <command> set コマンドで定義されたセッションセッティングを管理する。プロンプトで設定したセッティングを永続化できる。
inspect <setting-key> 値、説明、定義スコープ、依存関係、委譲チェーン、関連セッティングなど、セッティングに関する情報を表示する。

sbt runner とランチャー

システムシェルから sbt runner を起動する際、動作に影響を与える様々なシステムプロパティや JVM の追加オプションを指定できる。

sbt の JVM オプションとシステムプロパティ

sbt 起動時に JAVA_OPTS および/または SBT_OPTS 環境変数が定義されている場合、その内容は sbt server を実行する JVM にコマンドライン引数として渡される。

カレントディレクトリに .jvmopts という名前のファイルが存在する場合、sbt 起動時にその内容が JAVA_OPTS に追加される。同様に、.sbtopts および/または /etc/sbt/sbtopts が存在する場合、その内容が SBT_OPTS に追加される。JAVA_OPTS のデフォルト値は -Dfile.encoding=UTF8 である。

JVM のシステムプロパティとコマンドラインオプションは、sbt の引数として直接指定することもできる。-Dkey=val 形式の引数はそのまま JVM に渡され、-J-Xfoo は -Xfoo として渡される。

詳細はsbt --helpも参照。

sbt の JVM ヒープ、permgen、スタックサイズ

permgen やメモリが不足している場合は、他の Java アプリケーションと同様に JVMの設定を調整する必要がある。

例えば、メモリ関連の一般的なオプションは以下の通り:

export SBT_OPTS="-Xmx2048M -Xss2M"
sbt

現行セッションのみで指定したい場合:

sbt -J-Xmx2048M -J-Xss2M

ブートディレクトリ

sbt runner はただの起動スクリプトであり、実際の sbt server、Scala コンパイラ、標準ライブラリはデフォルトで共有ディレクトリ $HOME/.sbt/boot/ にダウンロードされる。

このディレクトリの場所を変更するには、sbt.boot.directory システムプロパティを設定する。相対パスはカレントワーキングディレクトリに対して解決される。プロジェクト間でブートディレクトリを共有したくない場合に便利である。例えば、以下は 0.11 以前のスタイルで project/boot/ にブートディレクトリを配置する:

sbt -Dsbt.boot.directory=project/boot/

ターミナルエンコーディング

ターミナルで使用する文字エンコーディングは、プラットフォームの Java デフォルトエンコーディングと異なる場合がある。その場合、file.encoding=<encoding> システムプロパティを指定する必要がある。例:

export JAVA_OPTS="-Dfile.encoding=Cp1252"
sbt

HTTP/HTTPS/FTP プロキシ

Unix では、sbt は標準の http_proxy、https_proxy、ftp_proxy 環境変数からHTTP、HTTPS、FTP のプロキシ設定を取得する。認証が必要なプロキシの内側にいる場合、sbt 起動時に追加のフラグを渡す必要がある。詳細はJVM ネットワーキングシステムプロパティを参照。

例:

sbt -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword

Windows では、スクリプトでプロキシホスト、ポート、必要に応じてユーザー名とパスワードのプロパティを設定する。例えば HTTP の場合:

sbt -Dhttp.proxyHost=myproxy -Dhttp.proxyPort=8080 -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword

上記のコマンドラインで http を https または ftp に置き換えて HTTPS または FTP を設定する。

その他のシステムプロパティ

以下のシステムプロパティも sbt runner に渡すことができる:

`-Dsbt.banner=true`

新機能を宣伝するウェルカムバナーを表示する。

`-Dsbt.ci=true`

デフォルトは false（環境変数 BUILD_NUMBER が設定されている場合を除く）。CI 環境用。supershell とカラー出力を抑制する。

`-Dsbt.client=true`

sbt クライアントを実行する。

`-Dsbt.color=auto`

カラーを有効にするには always または true を使用する。
カラーを無効にするには never または false を使用する。
出力がカラーをサポートするターミナル（パイプではない）の場合にカラーを使用するには auto を使用する。

The Book of sbt

sbt

概要

説明