Please read the earlier pages in the Getting Started Guide first, in particular you need to understand build.sbt, task graph, library dependencies, before reading this page.
A plugin extends the build definition, most commonly by adding new
settings. The new settings could be new tasks. For example, a plugin
could add a codeCoverage
task which would generate a test coverage
report.
If your project is in directory hello
, and you’re adding
sbt-site plugin to the build definition, create hello/project/site.sbt
and declare the plugin dependency by passing the plugin’s Ivy module ID
to addSbtPlugin
:
addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "0.7.0")
If you’re adding sbt-assembly, create hello/project/assembly.sbt
with the following:
addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.11.2")
Not every plugin is located on one of the default repositories and a plugin’s documentation may instruct you to also add the repository where it can be found:
resolvers ++= Resolver.sonatypeOssRepos("public")
Plugins usually provide settings that get added to a project to enable the plugin’s functionality. This is described in the next section.
A plugin can declare that its settings be automatically added to the build definition, in which case you don’t have to do anything to add them.
As of sbt 0.13.5, there is a new auto plugins feature that enables plugins to automatically, and safely, ensure their settings and dependencies are on a project. Many auto plugins should have their default settings automatically, however some may require explicit enablement.
If you’re using an auto plugin that requires explicit enablement, then you
have to add the following to your build.sbt
:
lazy val util = (project in file("util"))
.enablePlugins(FooPlugin, BarPlugin)
.settings(
name := "hello-util"
)
The enablePlugins
method allows projects to explicitly define the
auto plugins they wish to consume.
Projects can also exclude plugins using the disablePlugins
method. For example, if we wish to remove the IvyPlugin
settings
from util
, we modify our build.sbt
as follows:
lazy val util = (project in file("util"))
.enablePlugins(FooPlugin, BarPlugin)
.disablePlugins(plugins.IvyPlugin)
.settings(
name := "hello-util"
)
Auto plugins should document whether they need to be explicitly enabled. If you’re
curious which auto plugins are enabled for a given project, just run the
plugins
command on the sbt console.
For example:
> 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
Here, the plugins
output is showing that the sbt default plugins are all
enabled. sbt’s default settings are provided via three plugins:
CorePlugin
: Provides the core parallelism controls for tasks.
IvyPlugin
: Provides the mechanisms to publish/resolve modules.
JvmPlugin
: Provides the mechanisms to compile/test/run/package
Java/Scala projects.
In addition, JUnitXmlReportPlugin
provides an experimental support for
generating junit-xml.
Older non-auto plugins often require settings to be added explicitly, so that multi-project build could have different types of projects. The plugin documentation will indicate how to configure it, but typically for older plugins this involves adding the base settings for the plugin and customizing as necessary.
For example, for the sbt-site plugin, create site.sbt
with the following content
site.settings
to enable it for that project.
If the build defines multiple projects, instead add it directly to the project:
// 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)
Plugins can be installed for all your projects at once by declaring them
in $HOME/.sbt/1.0/plugins/
. $HOME/.sbt/1.0/plugins/
is an sbt project whose
classpath is exported to all sbt build definition projects. Roughly
speaking, any .sbt
or .scala
files in $HOME/.sbt/1.0/plugins/
behave as if
they were in the project/
directory for all projects.
You can create $HOME/.sbt/1.0/plugins/build.sbt
and put addSbtPlugin()
expressions in there to add plugins to all your projects at once.
Because doing so would increase the dependency on the machine environment,
this feature should be used sparingly. See
Best Practices.
There’s a list of available plugins.
Some especially popular plugins are:
For more details, including ways of developing plugins, see Plugins. For best practices, see Plugins-Best-Practices.