Appendix B. Migrating to autoplugins

 

So you want to use autoplugins. This quick guide explains how to take an existing (< sbt 0.13.0) plugin and upgrade it to the new AutoPlugin interface.

The sbt 0.13.5 release brought the developer preview of the new interface for plugins in sbt, called sbt.AutoPlugin. The new interface aims to fix two primary issues with sbt plugins:

  • The ability for plugins to automatically and safely register themselves into a user’s build
  • The ability for plugins to depend on other plugins

Before we discuss migrating, let’s look at how most plugins looked prior to sbt 0.13.5.

B.1. Older sbt plugins

Most plugins in the ecosystem are nothing more than jar files that contain a set of utility methods for the sbt DSL, one or more of which will be references to Seq[Setting[_]] that users can inject into their build.sbt files. For example, the sbt-assembly plugin you used in chapter 12 looks similar to the following: 

object SbtAssembly extends sbt.Plugin {
   def assemblySettings: Seq[Setting[_]] = ...
   lazy val mergeStrategy = taskKey ...
}

This object extends the sbt.Plugin interface. By default, sbt makes all members of such objects available inside build.sbt files. Although the older plugin API did include features to automatically add settings to sbt projects, these features led to innumerable problems in user builds, and the sbt community abandoned the features.

From a user’s perspective, all plugins required some addition to build.sbt. For example,

B.2. Migrating to autoplugins