sbt Plugins

Existing Plugins

• spde
• yuicompressor
• cuke4duke
• Android
• Installer
• sbt test framework

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.

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.5.4.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. The actual project for the plugin is at http://code.google.com/p/simple-build-tool/source/browse/#svn/trunk/install.

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.