sbt

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

書式

sbt
sbt command args
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-RC6

この機構によってビルドを特定のバージョンの 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>* 引数で指定されたテスト (省略された場合は全てのテスト) を以下の条件で実行する:
1. 未だ実行されていない、もしくは
2. 前回実行されたときに失敗した、もしくは
3. 前に成功してから間接的依存性のいずれかが再コンパイルされた
  * は、テスト名のワイルドカードとして解釈される。
testFull テストのコンパイル時に検知された全てのテストを実行する。

一般コマンド

shutdown sbt server をシャットダウンして現行の sbt セッションを終了する。
exit or quit End the current interactive session or build. Additionally, Ctrl+D (Unix) or Ctrl+Z (Windows) will exit the interactive prompt.
help <command> Displays detailed help for the specified command. If the command does not exist, help lists detailed help for commands whose name or description match the argument, which is interpreted as a regular expression. If no command is provided, displays brief descriptions of the main commands. Related commands are tasks and settings.
projects [add|remove <URI>] List all available projects if no arguments provided or adds/removes the build at the provided URI.

Watch command ~ <command> Executes the project specified action or method whenever source files change.
< filename Executes the commands in the given file. Each command should be on its own line. Empty lines and lines beginning with '#' are ignored
A ; B Execute A and if it succeeds, run B. Note that the leading semicolon is required.
eval <Scala-expression> Evaluates the given Scala expression and returns the result and inferred type. This can be used to set system properties, as a calculator, to fork processes, etc ... For example:
```
> eval System.setProperty("demo", "true")
> eval 1+1
> eval "ls -l" !
```

Commands for managing the build definition

reload [plugins|return] If no argument is specified, reloads the build, recompiling any build or plugin definitions as necessary. reload plugins changes the current project to the build definition project (in project/). This can be useful to directly manipulate the build definition. For example, running clean on the build definition project will force snapshots to be updated and the build definition to be recompiled. reload return changes back to the main project.
set <setting-expression> Evaluates and applies the given setting definition. The setting applies until sbt is restarted, the build is reloaded, or the setting is overridden by another set command or removed by the session command.
session <command> Manages session settings defined by the set command. It can persist settings configured at the prompt.
inspect <setting-key> Displays information about settings, such as the value, description, defining scope, dependencies, delegation chain, and related settings.

sbt runner and launcher

When launching the sbt runner from the system shell, various system properties or JVM extra options can be specified to influence its behaviour.

sbt JVM options and system properties

If the JAVA_OPTS and/or SBT_OPTS environment variables are defined when sbt starts, their content is passed as command line arguments to the JVM running sbt server.

If a file named .jvmopts exists in the current directory, its content is appended to JAVA_OPTS at sbt startup. Similarly, if .sbtopts and/or /etc/sbt/sbtopts exist, their content is appended to SBT_OPTS. The default value of JAVA_OPTS is -Dfile.encoding=UTF8.

You can also specify JVM system properties and command line options directly as sbt arguments: any -Dkey=val argument will be passed as-is to the JVM, and any -J-Xfoo will be passed as -Xfoo.

sbt JVM heap, permgen, and stack sizes

If you find yourself running out of permgen space or your workstation is low on memory, adjust the JVM configuration as you would for any java application.

For example a common set of memory-related options is:

export SBT_OPTS="-Xmx2048M -Xss2M"
sbt

Or if you prefer to specify them just for this session:

sbt -J-Xmx2048M -J-Xss2M

Boot directory

sbt runner is just a bootstrap, the actual sbt server, Scala compiler and standard library are by default downloaded to the shared directory \$HOME/.sbt/boot/.

To change the location of this directory, set the sbt.boot.directory system property. A relative path will be resolved against the current working directory, which can be useful if you want to avoid sharing the boot directory between projects. For example, the following uses the pre-0.11 style of putting the boot directory in project/boot/:

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

Terminal encoding

The character encoding used by your terminal may differ from Java's default encoding for your platform. In this case, you will need to specify the file.encoding=<encoding> system property, which might look like:

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

HTTP/HTTPS/FTP Proxy

On Unix, sbt will pick up any HTTP, HTTPS, or FTP proxy settings from the standard http_proxy, https_proxy, and ftp_proxy environment variables. If you are behind a proxy requiring authentication, you need to pass some supplementary flags at sbt startup. See JVM networking system properties for more details.

For example:

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

On Windows, your script should set properties for proxy host, port, and if applicable, username and password. For example, for HTTP:

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

Replace http with https or ftp in the above command line to configure HTTPS or FTP.

Other system properties

The following system properties can also be passed to sbt runner:

`-Dsbt.banner=true`

Show a welcome banner advertising new features.

`-Dsbt.ci=true`

Default false (unless then env var BUILD_NUMBER is set). For continuous integration environments. Suppress supershell and color.

`-Dsbt.client=true`

Run the sbt client.

`-Dsbt.color=auto`

To turn on color, use always or true.
To turn off color, use never or false.
To use color if the output is a terminal (not a pipe) that supports color, use auto.

The Book of sbt

sbt

書式

説明