Global plugins¶

The ~/.sbt/0.13/plugins/ directory is treated as a global plugin definition project. It is a normal sbt project whose classpath is available to all sbt project definitions for that user as described above for per-project plugins.

Using a library in a build definition¶

As an example, we'll add the Grizzled Scala library as a plugin. Although this does not provide sbt-specific functionality, it demonstrates how to declare plugins.

libraryDependencies += "org.clapper" %% "grizzled-scala" % "1.0.4"

$ sbt
> reload plugins
[info] Set current project to default (in build file:/Users/harrah/demo2/project/)
>

> set libraryDependencies += "org.clapper" %% "grizzled-scala" % "1.0.4"
...
> update
...
> session save
...

> reload return
[info] Set current project to root (in build file:/Users/harrah/demo2/)

lazy val root = project.in( file(".") ).dependsOn( assemblyPlugin )
lazy val assemblyPlugin = uri("git://github.com/sbt/sbt-assembly")

lazy val assemblyPlugin = uri("git://github.com/sbt/sbt-assembly#0.9.1")

> eval grizzled.sys.os

import grizzled.sys._
import OperatingSystem._

libraryDependencies ++=
    if(os ==Windows)
        ("org.example" % "windows-only" % "1.0") :: Nil
    else
        Nil

Introduction¶

A minimal plugin is a Scala library that is built against the version of Scala that sbt runs (currently, 2.10.4) or a Java library. Nothing special needs to be done for this type of library, as shown in the previous section. A more typical plugin will provide sbt tasks, commands, or settings. This kind of plugin may provide these settings automatically or make them available for the user to explicitly integrate.

Description¶

To make a plugin, create a project and configure sbtPlugin to true. Then, write the plugin code and publish your project to a repository. The plugin can be used as described in the previous section.

• Automatically importing selective names to .sbt files.
• Specifying plugin dependencies.
• Automatically activating itself when all dependencies are present.
• Specifying projectSettings, buildSettings, and globalSettings as appropriate.

When an AutoPlugin provides a stable field such as val or object named autoImport, the contents of the field are wildcard imported in in set, eval, and .sbt files. Typically, this is used to provide new keys (SettingKey, TaskKey, or InputKey) or core methods without requiring an import or qualification.

The AutoPlugin's projectSettings is automatically appended to each project's settings, when its dependencies also exist on that project. The requires method defines the dependencies to other plugins. The trigger method defines the conditions by which this plugin's settings are automatically activated. The buildSettings is appended to each build's settings (that is, in ThisBuild). The globalSettings is appended once to the global settings (in Global). These allow a plugin to automatically provide new functionality or new defaults. One main use of this feature is to globally add commands, such as for IDE plugins. Use globalSettings to define the default value of a setting.

Example Plugin¶

An example of a typical plugin:

build.sbt:

sbtPlugin := true

name := "sbt-obfuscate"

organization := "org.example"

Plugin.scala:

package sbtobfuscate

import sbt._

object Plugin extends AutoPlugin
{
    // by definging autoImport, these are automatically imported into user's `*.sbt`
    object autoImport
    {
        // configuration points, like the built in `version`, `libraryDependencies`, or `compile`
        val obfuscate = taskKey[Seq[File]]("Obfuscates files.")
        val obfuscateLiterals = settingKey[Boolean]("Obfuscate literals.")

        // default values for the tasks and settings
        lazy val baseObfuscateSettings: Seq[sbt.Def.Setting[_]] = Seq(
            obfuscate := {
                Obfuscate(sources.value, (obfuscateLiterals in obfuscate).value)
            },
            obfuscateLiterals in obfuscate := false
        )
    }

    import autoImport._
    override def requires = sbt.plugins.JvmModule

    // This plugin is automatically enabled for projects which are JvmModules.
    override def trigger = allRequirements

    // a group of settings that are automatically added to projects.
    override val projectSettings =
        inConfig(Compile)(baseObfucscateSettings) ++
        inConfig(Test)(baseObfuscateSettings)
}

object Obfuscate
{
    def apply(sources: Seq[File]): Seq[File] := sources
}

Usage example¶

A build definition that uses the plugin might look like:

obfuscate.sbt

obfuscateLiterals in obfuscate := true

Root Plugins¶

Some plugins should always be explicitly enabled on projects. Sbt calls these root plugins, i.e. plugins that are "root" nodes in the plugin depdendency graph. AutoPlugin by default defines a root plugin.

Example command root plugin¶

A basic plugin that adds commands looks like:

build.sbt

sbtPlugin := true

name := "sbt-sample"

organization := "org.example"

Plugin.scala

package sbtsample

import sbt._
import Keys._
object Plugin extends AutoPlugin
{
  override lazy val projectSettings = Seq(commands += myCommand)

  lazy val myCommand =
    Command.command("hello") { (state: State) =>
      println("Hi!")
      state
    }
}

This example demonstrates how to take a Command (here, myCommand) and distribute it in a plugin. Note that multiple commands can be included in one plugin (for example, use commands ++= Seq(a,b)). See Commands for defining more useful commands, including ones that accept arguments and affect the execution state.

For a user to consume this plugin, it requires an explicit include via the Project instance. Here's what their local sbt will look like.

build.sbt

val root = Project("example-plugin-usage", file(".")).setPlugins(MyPlugin)

The setPlugins method allows projects to explicitly define the `RootPlugin`s they wish to consume. `AutoPlugin`s are automatically added to the project as appropriate.

Projects can also exclude any type of plugin using the disablePlugins method. For example, if we wish to remove the JvmModule settings (compile,`test`,`run`), we modify our build.sbt as follows:

val root = Project("example-plugin-usage", file(".")).setPlugins(MyPlugin).disablePlugins(plugins.JvmModule)

Global plugins example¶

The simplest global plugin definition is declaring a library or plugin in ~/.sbt/0.13/plugins/build.sbt:

libraryDependencies += "org.example" %% "example-plugin" % "0.1"

This plugin will be available for every sbt project for the current user.

In addition:

1. Jars may be placed directly in ~/.sbt/0.13/plugins/lib/ and will be available to every build definition for the current user.
2. Dependencies on plugins built from source may be declared in ~/.sbt/0.13/plugins/project/Build.scala as described at .scala Build Definition.
3. A Plugin may be directly defined in Scala source files in ~/.sbt/0.13/plugins/, such as ~/.sbt/0.13/plugins/MyPlugin.scala. ~/.sbt/0.13/plugins//build.sbt should contain sbtPlugin := true. This can be used for quicker turnaround when developing a plugin initially:
   1. Edit the global plugin code
   2. reload the project you want to use the modified plugin in
   3. sbt will rebuild the plugin and use it for the project. Additionally, the plugin will be available in other projects on the machine without recompiling again. This approach skips the overhead of publishLocal and cleaning the plugins directory of the project using the plugin.

These are all consequences of ~/.sbt/0.13/plugins/ being a standard project whose classpath is added to every sbt project's build definition.

• Plugins
  • Introduction
  • Using a binary sbt plugin
  • By Description
    • Global plugins
  • By Example
    • Using a library in a build definition
      • 1a) Manually managed
      • 1b) Automatically managed: direct editing approach
      • 1c) Automatically managed: command line approach
      • 1d) Project dependency
      • 2) Use the library
  • Creating a plugin
    • Introduction
    • Description
    • Example Plugin
    • Usage example
    • Root Plugins
    • Example command root plugin
    • Global plugins example
  • Best Practices