Using plugins

What is a plugin?

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.

Declaring a plugin

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.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.

Enabling and disabling auto plugins

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:

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)

Global plugins

Plugins can be installed for all your projects at once by declaring them
in ~/.sbt/1.0/plugins/. ~/.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 ~/.sbt/1.0/plugins/ behave as if
they were in the project/ directory for all projects.

You can create ~/.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.