このガイドのこれまでのページを読んでおいてほしい。 特に build.sbt、 タスク・グラフ、 とライブラリ依存性を理解していることが必要になる。
sbt のプラグインは、最も一般的には新しいセッティングを追加することでビルド定義を拡張するものである。
その新しいセッティングは新しいタスクでもよい。
例えば、テストカバレッジレポートを生成する codeCoverage というタスクを追加するプラグインなどが考えられる。
プロジェクトが hello ディレクトリにあり、ビルド定義に sbt-site プラグインを追加する場合、
hello/project/site.sbt を新しく作成し、
Ivy のモジュール ID を addSbtPlugin メソッドに渡してプラグイン依存性を定義する:
addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "0.7.0")
sbt-assembly プラグインを追加するなら、以下のような内容で hello/project/assembly.sbt をつくる:
addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.11.2")
全てのプラグインがデフォルトのリポジトリに存在するわけではないので、 プラグインのドキュメントでそのプラグインが見つかるリポジトリを resolvers に追加するよう指示されていることもあるだろう。
resolvers ++= Resolver.sonatypeOssRepos("public")
プラグインは普通、プロジェクトでそのプラグインの機能を有効にするためのセッティング群を提供している。 これは次のセクションで説明する。
プラグインは、自身が持つセッティング群がビルド定義に自動的に追加されるよう宣言することができ、 その場合、プラグインの利用者は何もしなくてもいい。
sbt 0.13.5 から、プラグインを自動的に追加して、そのセッティング群と依存関係がプロジェクトに設定されていることを安全に保証する auto plugin という機能が追加された。
auto plugin の多くはデフォルトのセッティング群を自動的に追加するが、中には明示的な有効化を必要とするものもある。
明示的な有効化が必要な auto plugin を使っている場合は、以下を build.sbt に追加する必要がある:
lazy val util = (project in file("util"))
.enablePlugins(FooPlugin, BarPlugin)
.settings(
name := "hello-util"
)
enablePlugins メソッドを使えば、そのプロジェクトで使用したい auto plugin を明示的に定義できる。
逆に disablePlugins メソッドを使ってプラグインを除外することもできる。
例えば、util から IvyPlugin のセッティングを除外したいとすると、build.sbt を以下のように変更する:
lazy val util = (project in file("util"))
.enablePlugins(FooPlugin, BarPlugin)
.disablePlugins(plugins.IvyPlugin)
.settings(
name := "hello-util"
)
明示的な有効化が必要か否かは、それぞれの auto plugin がドキュメントで明記しておくべきだ。
あるプロジェクトでどんな auto plugin が有効化されているか気になったら、
sbt コンソールから plugins コマンドを実行してみよう。
例えば、このようになる。
> plugins
In file:/home/jsuereth/projects/sbt/test-ivy-issues/
sbt.plugins.IvyPlugin: enabled in scala-sbt-org
sbt.plugins.JvmPlugin: enabled in scala-sbt-org
sbt.plugins.CorePlugin: enabled in scala-sbt-org
sbt.plugins.JUnitXmlReportPlugin: enabled in scala-sbt-org
ここでは、plugins の表示によって sbt のデフォルトのプラグインが全て有効化されていることが分かる。
sbt のデフォルトセッティングは 3 つのプラグインによって提供される:
CorePlugin: タスクの並列実行などのコア機能。
IvyPlugin: モジュールの公開や依存性の解決機能。
JvmPlugin: Java/Scala プロジェクトのコンパイル/テスト/実行/パッケージ化。
さらに JUnitXmlReportPlugin は実験的に junit-xml の生成機能を提供する。
古くからある auto plugin ではないプラグインは、マルチプロジェクトビルド内に 異なるタイプのプロジェクトを持つことができるように、セッティング群を明示的に追加することを必要とする。
各プラグインのドキュメントに設定方法が明記されているかと思うが、 一般的にはベースとなるセッティング群を追加して、必要に応じてカスタマイズするというパターンが多い。
例えば sbt-site プラグインの例で説明すると site.sbt というファイルを新しく作って
site.settings
を site.sbt に記述することで有効化できる。
ビルド定義がマルチプロジェクトの場合は、プロジェクトに直接追加する:
// don't use the site plugin for the `util` project
lazy val util = (project in file("util"))
// enable the site plugin for the `core` project
lazy val core = (project in file("core"))
.settings(site.settings)
プラグインを $HOME/.sbt/1.0/plugins/ 以下で宣言することで全てのプロジェクトに対して一括してプラグインをインストールすることができる。
$HOME/.sbt/1.0/plugins/ はそのクラスパスをすべての sbt ビルド定義に対して export する sbt プロジェクトだ。
大雑把に言えば、$HOME/.sbt/1.0/plugins/ 内の .sbt ファイルや .scala ファイルは、それが全てのプロジェクトの project/ ディレクトリに入っているかのようにふるまう。
$HOME/.sbt/1.0/plugins/build.sbt を作って、そこに addSbtPlugin() 式を書くことで
全プロジェクトにプラグインを追加することができる。
しかし、これを多用するとマシン環境への依存性を増やしてしまうことになるので、この機能は注意してほどほどに使うべきだ。
ベスト・プラクティスも参照してほしい。
プラグインのリストがある。
特に人気のプラグインは:
プラグイン開発の方法など、プラグインに関する詳細は Plugins を参照。 ベストプラクティスを知りたいなら、ベスト・プラクティス を見てほしい。
