1. Developer’s Guide (Work in progress)

Developer’s Guide (Work in progress) 

This is the set of documentation about the future architecture of sbt. The target audience of this document is the sbt plugin authors and sbt developers. See also How can I help?

Towards sbt 1.0 

On 2008-12-18, Mark Harrah announced sbt 0.3.2 as the initial release of sbt. Mark remained the primary author of sbt until sbt 0.13.1 (2013-12-11). In 2014, sbt project was handed over to the authors of this document Josh Suereth and Eugene Yokota.

As we move towards sbt 1.0, we wish to stabilize what’s already stable and innovate where it matters. There are several levels of stability:

  • conceptual stability
  • source compatibility of the build definition
  • binary compatibility of the plugins

Concepts 

Conceptually, sbt has been stable on what it does:

  1. incremental compilation that supports Scala
  2. dependency management that’s aware of Scala’s binary compatibility
  3. task and plugins system that’s extensible using Scala
  4. a text-based interactive shell

The only thing that we plan to change is the last point. In sbt 1.0, we will replace the interactive shell with sbt server that’s accessible via JSON API and a text-based client.

Source compatibility of the build definition 

Source compatibility means that a build source that worked for sbt version A works for another version B without modification. Our goal for sbt 1.0 is to adopt Semantic Versioning, and maintain source compatibility of the build during 1.x.y.

Binary compatibility of the plugins 

Binary compatibility (“bincompat”) of the plugins means that a plugin that was published for sbt version A works for another version B without recompilation. sbt 0.13 has kept binary compatibility for 18 months as of March 2015. The stability here helps maintain the sbt plugin ecosystem. Our goal for sbt 1.0 is to adopt Semantic Versioning, and maintain binary compatibility of the build during 1.x.y.

From the development perspective, maintaining binary compatibility becomes an additional constraint that we need to worry about whenever we make changes. The root of the problem is that sbt 0.13 does not distinguish between public API and internal implementation. Most things are open to plugins.