sbt has moved

sbt has now completely moved to GitHub.

See https://github.com/harrah/xsbt/wiki/Plugins.

sbt Plugins

Existing Plugins

• spde
• bnd4sbt
• yuicompressor
• cuke4duke
• Android
• Installer
• sbt test framework
• EditSource, IzPack, and Markdown
• JRebel
• Jython
• FindBugs
• Copy/Paste Detector (CPD) of PMD
• Resource Filtering

See Integration Support for IDE-related plugins.

See also the complementary extension mechanism Processors, which includes a list of existing processors.

Basics

Plugins are libraries for your project definition. Declare them like dependencies for your project, except in a plugin definition in the project/plugins/ directory. For example, to use MarkdownJ in your project definition, create:

project/plugins/Plugins.scala

import sbt._
class Plugins(info: ProjectInfo) extends PluginDefinition(info)
{
  val a = "org.markdownj" % "markdownj" % "0.3.0-1.0.2b4"
}

Verify it is correct by doing reload and then console-project. Call some MarkdownJ code:

scala> new com.petebevin.markdown.MarkdownProcessor
res1: com.petebevin.markdown.MarkdownProcessor = Markdown Processor for Java 0.3.0 (compatible with Markdown 1.0.2b2)

This dependency was independent of sbt. You can also create and use plugins that extend or use sbt. The rest of this page describes sbt plugins. The first part shows the results of a plugin that creates a self-extracting jar out of a project. The second part shows how to create a simple plugin that provides a new action to a project.

Hello Lift Installer Example

• Download the jar
• Run java -jar hello-lift-1.0-setup.jar . The Hello Lift project and an embedded sbt launcher will be extracted. The project will be loaded and predefined actions run. In this case, the project will be set up, dependencies will be downloaded, and the project will be compiled and Jetty started. Browse to http://localhost:8080.
• You have a ready example Lift project. For example, you can enter the extracted project directory and start sbt with java -jar sbt-launcher-0.7.1.jar.
• The project uses Scala X-Ray to generate browsable sources. You can view these in the project/target/classes.sxr directory.
• You can run installer to regenerate the self-extracting jar from the project. Note: there is currently the issue of including the sbt-launcher in the project zip, making the jar substantially larger than necessary.
• See the project/plugins/Plugins.scala directory for how the plugin is defined or see the Installer Plugin section below.

Hello World Plugin

To try out plugins, we'll make a simple hello world plugin and use it.

Make the Plugin

To make a plugin, create a new project with a project definition that extends PluginProject. This can now go in project/build. The basic example:

  import sbt._
  class TestPluginProject(info: ProjectInfo) extends PluginProject(info)

Make a simple plugin by putting the following in src/main/scala :

package hw
import sbt._
trait HelloWorldPlugin extends Project {
  lazy val hello = task { log.info("Hello World!"); None }
}

Publish it by running the publish-local action.

Use the Plugin

To use the plugin, create a new project. Declare plugins by putting a plugin definition (basically a project definition that extends PluginDefinition) in project/plugins/. The following example assumes that the plugin above had was setup with the name "test" and with version "1.0".

import sbt._
class Plugins(info: ProjectInfo) extends PluginDefinition(info) {
  val a = "test" % "test" % "1.0"
}

Define the project definition in project/build/ to use the HelloWorldPlugin :

import sbt._
class TestProject(info: ProjectInfo) extends DefaultProject(info) with hw.HelloWorldPlugin

Try it out by running the hello action at the prompt.

Details

sbt plugins are a way to reuse code between project definitions. They can consist of any Scala code you want. Specifically, they are not restricted to providing a single trait extending Project, as in the example.

You can provide a trait that extends Project, DefaultProject, or DefaultWebProject that the user then mixes in to use. You can provide multiple project types or you can just provide code that can be used to implement tasks.

See the Existing Plugins section at the top of the page for examples of plugins.

Installer Plugin

The installer plugin provides a task 'installer' that creates a self-executable jar that bundles the current project. When executed, the jar will extract the sbt launcher and the project, run sbt on the project, and execute predefined commands.

To use it, first declare the plugin:

project/plugins/Plugins.scala

import sbt._
class Plugins(info: ProjectInfo) extends PluginDefinition(info) {
  val extract = "org.scala-tools.sbt" % "installer-plugin" % "0.3.0"
}

Then, mix the BasicSelfExtractingProject trait into your build definition:

project/build/YourProject.scala

import sbt._
class YourProject(info: ProjectInfo) extends DefaultProject(info) 
  with extract.BasicSelfExtractingProject
{
  override def installActions = "update" :: "run" :: Nil
}

Overriding installActions is optional. It defines the actions that sbt runs after the project is extracted. By default, 'update' and 'compile' are run.

Finally, create the self-extracting jar by running the installer action on the project. The resulting jar can be run with java -jar ....

The installer project is a subproject of sbt in the sbt/install/ directory.