Using Plugins¶

Dependencies for the build definition¶

Adding a plugin means adding a library dependency to the build definition. To do that, you edit the build definition for the build definition.

Recall that for a project hello, its build definition project lives in hello/*.sbt and hello/project/*.scala:

hello/                  # your project's base directory

    build.sbt           # build.sbt is part of the source code for the
                        #   build definition project inside project/

    project/            # base directory of the build definition project

        Build.scala     # a source file in the project/ project,
                        #   that is, a source file in the build definition

If you wanted to add a managed dependency to project hello, you would add to the libraryDependencies setting either in hello/*.sbt or hello/project/*.scala.

You could add this in hello/build.sbt:

libraryDependencies += "org.apache.derby" % "derby" % "10.4.1.3" % "test"

If you add that and start up the sbt interactive mode and type show dependency-classpath, you should see the derby jar on your classpath.

To add a plugin, do the same thing but recursed one level. We want the build definition project to have a new dependency. That means changing the libraryDependencies setting for the build definition of the build definition.

The build definition of the build definition, if your project is hello, would be in hello/project/*.sbt and hello/project/project/*.scala.

The simplest "plugin" has no special sbt support; it's just a jar file. For example, edit hello/project/build.sbt and add this line:

libraryDependencies += "net.liftweb" % "lift-json" % "2.0"

Now, at the sbt interactive prompt, reload plugins to enter the build definition project, and try show dependency-classpath. You should see the lift-json jar on the classpath. This means: you could use classes from lift-json in your Build.scala or build.sbt to implement a task. You could parse a JSON file and generate other files based on it, for example. Remember, use reload return to leave the build definition project and go back to the parent project.

(Stupid sbt trick: type reload plugins over and over. You'll find yourself in the project rooted in project/project/project/project/project/project/. Don't worry, it isn't useful. Also, it creates target directories all the way down, which you'll have to clean up.)

addSbtPlugin¶

addSbtPlugin is just a convenience method. Here's its definition:

def addSbtPlugin(dependency: ModuleID): Setting[Seq[ModuleID]] =
  libraryDependencies <+= (sbtVersion in update,scalaVersion) { (sbtV, scalaV) =>
    sbtPluginExtra(dependency, sbtV, scalaV)
  }

Remember from more about settings that <+= combines <<= and +=, so this builds a value based on other settings, and then appends it to libraryDependencies. The value is based on sbtVersion in update (sbt's version scoped to the update task) and scalaVersion (the version of scala used to compile the project, in this case used to compile the build definition). sbtPluginExtra adds the sbt and Scala version information to the module ID.

plugins.sbt¶

Some people like to list plugin dependencies (for a project hello) in hello/project/plugins.sbt to avoid confusion with hello/build.sbt. sbt does not care what .sbt files are called, so both build.sbt and project/plugins.sbt are conventions. sbt does of course care where the sbt files are located. hello/*.sbt would contain dependencies for hello and hello/project/*.sbt would contain dependencies for hello's build definition.