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
If your project is in directory
hello, and you’re adding
sbt-site plugin to the build definition, create
and declare the plugin dependency by passing the plugin’s Ivy module ID
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.sonatypeRepo("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
lazy val util = (project in file("util")) .enablePlugins(FooPlugin, BarPlugin) .settings( name := "hello-util" )
enablePlugins method allows projects to explicitly define the
auto plugins they wish to consume.
Projects can also exclude plugins using the
method. For example, if we wish to remove the
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.
> 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 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.
JUnitXmlReportPlugin provides an experimental support for
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
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
$HOME/.sbt/1.0/plugins/ is an sbt project whose
classpath is exported to all sbt build definition projects. Roughly
.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
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
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.