sbt Reference Manual 

sbt is a build tool for Scala, Java, and more. It requires Java 1.8 or later.

Install 

See Installing sbt for the setup instructions.

Getting Started 

To get started, please read the Getting Started Guide. You will save yourself a lot of time if you have the right understanding of the big picture up-front. All documentation may be found via the table of contents included on the left of every page.

See also Frequently asked question.

See How can I get help? for where you can get help about sbt. For discussing sbt development, use Discussions. To stay up to date about the news related to sbt, follow us @scala_sbt.

Features of sbt 

• Little or no configuration required for simple projects
• Scala-based build definition that can use the full flexibility of Scala code
• Accurate incremental recompilation using information extracted from the compiler
• Library management support using Coursier
• Continuous compilation and testing with triggered execution
• Supports mixed Scala/Java projects
• Supports testing with ScalaCheck, specs, and ScalaTest. JUnit is supported by a plugin.
• Starts the Scala REPL with project classes and dependencies on the classpath
• Modularization supported with sub-projects
• External project support (list a git repository as a dependency!)
• Parallel task execution, including parallel test execution

Also 

This documentation can be forked on GitHub. Feel free to make corrections and add documentation.

Documentation for 0.13.x has been archived here. This documentation applies to sbt 1.9.8.

See also the API Documentation, and the index of names and types.

Getting Started with sbt 

sbt uses a small number of concepts to support flexible and powerful build definitions. There are not that many concepts, but sbt is not exactly like other build systems and there are details you will stumble on if you haven’t read the documentation.

The Getting Started Guide covers the concepts you need to know to create and maintain an sbt build definition.

It is highly recommended to read the Getting Started Guide!

If you are in a huge hurry, the most important conceptual background can be found in build definition, scopes, and task graph. But we don’t promise that it’s a good idea to skip the other pages in the guide.

It’s best to read in order, as later pages in the Getting Started Guide build on concepts introduced earlier.

Thanks for trying out sbt and have fun!

Installing sbt 

To create an sbt project, you’ll need to take these steps:

• Install JDK (We recommend Eclipse Adoptium Temurin JDK 8, 11, or 17).
• Install sbt.
• Setup a simple hello world project
• Move on to running to learn how to run sbt.
• Then move on to .sbt build definition to learn more about build definitions.

Ultimately, the installation of sbt boils down to a launcher JAR and a shell script, but depending on your platform, we provide several ways to make the process less tedious. Head over to the installation steps for macOS, Windows, or Linux.

Tips and Notes 

If you have any trouble running sbt, see Command line reference on JVM options.

Installing sbt on macOS 

Install sbt with cs setup 

Follow Install page, and install Scala using Coursier. This should install the latest stable version of sbt.

Install JDK 

Follow the link to install JDK 8 or 11, or use SDKMAN!.

SDKMAN! 

$ sdk install java $(sdk list java | grep -o "\b8\.[0-9]*\.[0-9]*\-tem" | head -1)
$ sdk install sbt

Installing from a universal package 

Download ZIP or TGZ package, and expand it.

Installing from a third-party package 

Note: Third-party packages may not provide the latest version. Please make sure to report any issues with these packages to the relevant maintainers.

Homebrew 

$ brew install sbt

Installing sbt on Windows 

Install sbt with cs setup 

Follow Install page, and install Scala using Coursier. This should install the latest stable version of sbt.

Install JDK 

Follow the link to install JDK 8 or 11.

Installing from a universal package 

Download ZIP or TGZ package and expand it.

Windows installer 

Download msi installer and install it.

Installing from a third-party package 

Note: Third-party packages may not provide the latest version. Please make sure to report any issues with these packages to the relevant maintainers.

Scoop 

$ scoop install sbt

Chocolatey 

$ choco install sbt

Installing sbt on Linux 

Install sbt with cs setup 

Follow Install page, and install Scala using Coursier. This should install the latest stable version of sbt.

Installing from SDKMAN 

To install both JDK and sbt, consider using SDKMAN.

$ sdk install java $(sdk list java | grep -o "\b8\.[0-9]*\.[0-9]*\-tem" | head -1)
$ sdk install sbt

Using Coursier or SDKMAN has two advantages.

1. They will install the official packaging by Eclipse Adoptium, as opposed to the “mystery meat OpenJDK builds“.
2. They will install tgz packaging of sbt that contains all JAR files. (DEB and RPM packages do not to save bandwidth)

Install JDK 

You must first install a JDK. We recommend Eclipse Adoptium Temurin JDK 8, JDK 11, or JDK 17.

The details around the package names differ from one distribution to another. For example, Ubuntu xenial (16.04LTS) has openjdk-8-jdk. Redhat family calls it java-1.8.0-openjdk-devel.

Installing from a universal package 

Download ZIP or TGZ package and expand it.

Ubuntu and other Debian-based distributions 

DEB package is officially supported by sbt.

Ubuntu and other Debian-based distributions use the DEB format, but usually you don’t install your software from a local DEB file. Instead they come with package managers both for the command line (e.g. apt-get, aptitude) or with a graphical user interface (e.g. Synaptic). Run the following from the terminal to install sbt (You’ll need superuser privileges to do so, hence the sudo).

sudo apt-get update
sudo apt-get install apt-transport-https curl gnupg -yqq
echo "deb https://repo.scala-sbt.org/scalasbt/debian all main" | sudo tee /etc/apt/sources.list.d/sbt.list
echo "deb https://repo.scala-sbt.org/scalasbt/debian /" | sudo tee /etc/apt/sources.list.d/sbt_old.list
curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" | sudo -H gpg --no-default-keyring --keyring gnupg-ring:/etc/apt/trusted.gpg.d/scalasbt-release.gpg --import
sudo chmod 644 /etc/apt/trusted.gpg.d/scalasbt-release.gpg
sudo apt-get update
sudo apt-get install sbt

Package managers will check a number of configured repositories for packages to offer for installation. You just have to add the repository to the places your package manager will check.

Once sbt is installed, you’ll be able to manage the package in aptitude or Synaptic after you updated their package cache. You should also be able to see the added repository at the bottom of the list in System Settings -> Software & Updates -> Other Software:

Note: There have been reports about SSL error using Ubuntu: Server access Error: java.lang.RuntimeException: Unexpected error: java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty url=https://repo1.maven.org/maven2/org/scala-sbt/sbt/1.1.0/sbt-1.1.0.pom, which apparently stems from OpenJDK 9 using PKCS12 format for /etc/ssl/certs/java/cacerts cert-bug. According to https://stackoverflow.com/a/50103533/3827 it is fixed in Ubuntu Cosmic (18.10), but Ubuntu Bionic LTS (18.04) is still waiting for a release. See the answer for a workaround.

Note: sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com:443 --recv 2EE0EA64E40A89B84B2DF73499E82A75642AC823 may not work on Ubuntu Bionic LTS (18.04) since it’s using a buggy GnuPG, so we are advising to use web API to download the public key in the above.

Red Hat Enterprise Linux and other RPM-based distributions 

RPM package is officially supported by sbt.

Red Hat Enterprise Linux and other RPM-based distributions use the RPM format. Run the following from the terminal to install sbt (You’ll need superuser privileges to do so, hence the sudo).

# remove old Bintray repo file
sudo rm -f /etc/yum.repos.d/bintray-rpm.repo
curl -L https://www.scala-sbt.org/sbt-rpm.repo > sbt-rpm.repo
sudo mv sbt-rpm.repo /etc/yum.repos.d/
sudo yum install sbt

On Fedora (31 and above), use sbt-rpm.repo:

# remove old Bintray repo file
sudo rm -f /etc/yum.repos.d/bintray-rpm.repo
curl -L https://www.scala-sbt.org/sbt-rpm.repo > sbt-rpm.repo
sudo mv sbt-rpm.repo /etc/yum.repos.d/
sudo dnf install sbt

Note: Please report any issues with these to the sbt project.

Gentoo 

The official tree contains ebuilds for sbt. To install the latest available version do:

emerge dev-java/sbt

sbt by example 

This page assumes you’ve installed sbt 1.

Let’s start with examples rather than explaining how sbt works or why.

Create a minimum sbt build 

$ mkdir foo-build
$ cd foo-build
$ touch build.sbt

Start sbt shell 

$ sbt
[info] Updated file /tmp/foo-build/project/build.properties: set sbt.version to 1.9.3
[info] welcome to sbt 1.9.3 (Eclipse Adoptium Java 17.0.8)
[info] Loading project definition from /tmp/foo-build/project
[info] loading settings for project foo-build from build.sbt ...
[info] Set current project to foo-build (in build file:/tmp/foo-build/)
[info] sbt server started at local:///Users/eed3si9n/.sbt/1.0/server/abc4fb6c89985a00fd95/sock
[info] started sbt server
sbt:foo-build>

Exit sbt shell 

To leave sbt shell, type exit or use Ctrl+D (Unix) or Ctrl+Z (Windows).

sbt:foo-build> exit

Compile a project 

As a convention, we will use the sbt:...> or > prompt to mean that we’re in the sbt interactive shell.

$ sbt
sbt:foo-build> compile

Recompile on code change 

Prefixing the compile command (or any other command) with ~ causes the command to be automatically re-executed whenever one of the source files within the project is modified. For example:

sbt:foo-build> ~compile
[success] Total time: 0 s, completed 28 Jul 2023, 13:32:35
[info] 1. Monitoring source files for foo-build/compile...
[info]    Press <enter> to interrupt or '?' for more options.

Create a source file 

Leave the previous command running. From a different shell or in your file manager create in the foo-build directory the following nested directories: src/main/scala/example. Then, create Hello.scala in the example directory using your favorite editor as follows:

package example

object Hello {
  def main(args: Array[String]): Unit = {
    println("Hello")
  }
}

This new file should be picked up by the running command:

[info] Build triggered by /tmp/foo-build/src/main/scala/example/Hello.scala. Running 'compile'.
[info] compiling 1 Scala source to /tmp/foo-build/target/scala-2.12/classes ...
[success] Total time: 0 s, completed 28 Jul 2023, 13:38:55
[info] 2. Monitoring source files for foo-build/compile...
[info]    Press <enter> to interrupt or '?' for more options.

Press Enter to exit ~compile.

Run a previous command 

From sbt shell, press up-arrow twice to find the compile command that you executed at the beginning.

sbt:foo-build> compile

Getting help 

Use the help command to get basic help about the available commands.

sbt:foo-build> help

  <command> (; <command>)*                       Runs the provided semicolon-separated commands.
  about                                          Displays basic information about sbt and the build.
  tasks                                          Lists the tasks defined for the current project.
  settings                                       Lists the settings defined for the current project.
  reload                                         (Re)loads the current project or changes to plugins project or returns from it.
  new                                            Creates a new sbt build.
  new                                            Creates a new sbt build.
  projects                                       Lists the names of available projects or temporarily adds/removes extra builds to the session.

....

Display the description of a specific task:

sbt:foo-build> help run
Runs a main class, passing along arguments provided on the command line.

Run your app 

sbt:foo-build> run
[info] running example.Hello
Hello
[success] Total time: 0 s, completed 28 Jul 2023, 13:40:31

Set ThisBuild / scalaVersion from sbt shell 

sbt:foo-build> set ThisBuild / scalaVersion := "2.13.12"
[info] Defining ThisBuild / scalaVersion
[info] The new value will be used by Compile / bspBuildTarget, Compile / dependencyTreeCrossProjectId and 50 others.
[info]  Run `last` for details.
[info] Reapplying settings...
[info] set current project to foo-build (in build file:/tmp/foo-build/)

Check the scalaVersion setting:

sbt:foo-build> scalaVersion
[info] 2.13.12

Save the session to build.sbt 

We can save the ad-hoc settings using session save.

sbt:foo-build> session save
[info] Reapplying settings...
[info] set current project to foo-build (in build file:/tmp/foo-build/)
[warn] build source files have changed
[warn] modified files:
[warn]   /tmp/foo-build/build.sbt
[warn] Apply these changes by running `reload`.
[warn] Automatically reload the build when source changes are detected by setting `Global / onChangedBuildSource := ReloadOnSourceChanges`.
[warn] Disable this warning by setting `Global / onChangedBuildSource := IgnoreSourceChanges`.

build.sbt file should now contain:

ThisBuild / scalaVersion := "2.13.12"

Name your project 

Using an editor, change build.sbt as follows:

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

lazy val hello = (project in file("."))
  .settings(
    name := "Hello"
  )

Reload the build 

Use the reload command to reload the build. The command causes the build.sbt file to be re-read, and its settings applied.

sbt:foo-build> reload
[info] welcome to sbt 1.9.3 (Eclipse Adoptium Java 17.0.8)
[info] loading project definition from /tmp/foo-build/project
[info] loading settings for project hello from build.sbt ...
[info] set current project to Hello (in build file:/tmp/foo-build/)
sbt:Hello>

Note that the prompt has now changed to sbt:Hello>.

Add toolkit-test to libraryDependencies 

Using an editor, change build.sbt as follows:

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

lazy val hello = project
  .in(file("."))
  .settings(
    name := "Hello",
    libraryDependencies += "org.scala-lang" %% "toolkit-test" % "0.1.7" % Test
  )

Use the reload command to reflect the change in build.sbt.

sbt:Hello> reload

Run tests 

sbt:Hello> test

Run incremental tests continuously 

sbt:Hello> ~testQuick

Write a test 

Leaving the previous command running, create a file named src/test/scala/example/HelloSuite.scala using an editor:

class HelloSuite extends munit.FunSuite {
  test("Hello should start with H") {
    assert("hello".startsWith("H"))
  }
}

~testQuick should pick up the change:

[info] 2. Monitoring source files for hello/testQuick...
[info]    Press <enter> to interrupt or '?' for more options.
[info] Build triggered by /tmp/foo-build/src/test/scala/example/HelloSuite.scala. Running 'testQuick'.
[info] compiling 1 Scala source to /tmp/foo-build/target/scala-2.13/test-classes ...
HelloSuite:
==> X HelloSuite.Hello should start with H  0.004s munit.FailException: /tmp/foo-build/src/test/scala/example/HelloSuite.scala:4 assertion failed
3:  test("Hello should start with H") {
4:    assert("hello".startsWith("H"))
5:  }
    at munit.FunSuite.assert(FunSuite.scala:11)
    at HelloSuite.$anonfun$new$1(HelloSuite.scala:4)
[error] Failed: Total 1, Failed 1, Errors 0, Passed 0
[error] Failed tests:
[error]         HelloSuite
[error] (Test / testQuick) sbt.TestsFailedException: Tests unsuccessful

Make the test pass 

Using an editor, change src/test/scala/example/HelloSuite.scala to:

class HelloSuite extends munit.FunSuite {
  test("Hello should start with H") {
    assert("Hello".startsWith("H"))
  }
}

Confirm that the test passes, then press Enter to exit the continuous test.

Add a library dependency 

Using an editor, change build.sbt as follows:

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

lazy val hello = project
  .in(file("."))
  .settings(
    name := "Hello",
    libraryDependencies ++= Seq(
      "org.scala-lang" %% "toolkit" % "0.1.7",
      "org.scala-lang" %% "toolkit-test" % "0.1.7" % Test
    )
  )

Use the reload command to reflect the change in build.sbt.

Use Scala REPL 

We can find out the current weather in New York.

sbt:Hello> console
[info] Starting scala interpreter...
Welcome to Scala 2.13.12 (OpenJDK 64-Bit Server VM, Java 17).
Type in expressions for evaluation. Or try :help.

scala> :paste
// Entering paste mode (ctrl-D to finish)

import sttp.client4.quick._
import sttp.client4.Response

val newYorkLatitude: Double = 40.7143
val newYorkLongitude: Double = -74.006
val response: Response[String] = quickRequest
  .get(
    uri"https://api.open-meteo.com/v1/forecast?latitude=$newYorkLatitude&longitude=$newYorkLongitude&current_weather=true"
  )
  .send()

println(ujson.read(response.body).render(indent = 2))

// press Ctrl+D

// Exiting paste mode, now interpreting.

{
  "latitude": 40.710335,
  "longitude": -73.99307,
  "generationtime_ms": 0.36704540252685547,
  "utc_offset_seconds": 0,
  "timezone": "GMT",
  "timezone_abbreviation": "GMT",
  "elevation": 51,
  "current_weather": {
    "temperature": 21.3,
    "windspeed": 16.7,
    "winddirection": 205,
    "weathercode": 3,
    "is_day": 1,
    "time": "2023-08-04T10:00"
  }
}
import sttp.client4.quick._
import sttp.client4.Response
val newYorkLatitude: Double = 40.7143
val newYorkLongitude: Double = -74.006
val response: sttp.client4.Response[String] = Response({"latitude":40.710335,"longitude":-73.99307,"generationtime_ms":0.36704540252685547,"utc_offset_seconds":0,"timezone":"GMT","timezone_abbreviation":"GMT","elevation":51.0,"current_weather":{"temperature":21.3,"windspeed":16.7,"winddirection":205.0,"weathercode":3,"is_day":1,"time":"2023-08-04T10:00"}},200,,List(:status: 200, content-encoding: deflate, content-type: application/json; charset=utf-8, date: Fri, 04 Aug 2023 10:09:11 GMT),List(),RequestMetadata(GET,https://api.open-meteo.com/v1/forecast?latitude=40.7143&longitude...

scala> :q // to quit

Make a subproject 

Change build.sbt as follows:

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

lazy val hello = project
  .in(file("."))
  .settings(
    name := "Hello",
    libraryDependencies ++= Seq(
      "org.scala-lang" %% "toolkit" % "0.1.7",
      "org.scala-lang" %% "toolkit-test" % "0.1.7" % Test
    )
  )

lazy val helloCore = project
  .in(file("core"))
  .settings(
    name := "Hello Core"
  )

Use the reload command to reflect the change in build.sbt.

List all subprojects 

sbt:Hello> projects
[info] In file:/tmp/foo-build/
[info]   * hello
[info]     helloCore

Compile the subproject 

sbt:Hello> helloCore/compile

Add toolkit-test to the subproject 

Change build.sbt as follows:

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

val toolkitTest = "org.scala-lang" %% "toolkit-test" % "0.1.7"

lazy val hello = project
  .in(file("."))
  .settings(
    name := "Hello",
    libraryDependencies ++= Seq(
      "org.scala-lang" %% "toolkit" % "0.1.7",
      toolkitTest % Test
    )
  )

lazy val helloCore = project
  .in(file("core"))
  .settings(
    name := "Hello Core",
    libraryDependencies += toolkitTest % Test
  )

Broadcast commands 

Set aggregate so that the command sent to hello is broadcast to helloCore too:

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

val toolkitTest = "org.scala-lang" %% "toolkit-test" % "0.1.7"

lazy val hello = project
  .in(file("."))
  .aggregate(helloCore)
  .settings(
    name := "Hello",
    libraryDependencies ++= Seq(
      "org.scala-lang" %% "toolkit" % "0.1.7",
      toolkitTest % Test
    )
  )

lazy val helloCore = project
  .in(file("core"))
  .settings(
    name := "Hello Core",
    libraryDependencies += toolkitTest % Test
  )

After reload, ~testQuick now runs on both subprojects:

sbt:Hello> ~testQuick

Press Enter to exit the continuous test.

Make hello depend on helloCore 

Use .dependsOn(...) to add a dependency on other subprojects. Also let’s move the toolkit dependency to helloCore.

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

val toolkitTest = "org.scala-lang" %% "toolkit-test" % "0.1.7"

lazy val hello = project
  .in(file("."))
  .aggregate(helloCore)
  .dependsOn(helloCore)
  .settings(
    name := "Hello",
    libraryDependencies += toolkitTest % Test
  )

lazy val helloCore = project
  .in(file("core"))
  .settings(
    name := "Hello Core",
    libraryDependencies += "org.scala-lang" %% "toolkit" % "0.1.7",
    libraryDependencies += toolkitTest % Test
  )

Parse JSON using uJson 

Let’s use uJson from the toolkit in helloCore.

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

val toolkitTest = "org.scala-lang" %% "toolkit-test" % "0.1.7"

lazy val hello = project
  .in(file("."))
  .aggregate(helloCore)
  .dependsOn(helloCore)
  .settings(
    name := "Hello",
    libraryDependencies += toolkitTest % Test
  )

lazy val helloCore = project
  .in(file("core"))
  .settings(
    name := "Hello Core",
    libraryDependencies += "org.scala-lang" %% "toolkit" % "0.1.7",
    libraryDependencies += toolkitTest % Test
  )

After reload, add core/src/main/scala/example/core/Weather.scala:

package example.core

import sttp.client4.quick._
import sttp.client4.Response

object Weather {
  def temp() = {
    val response: Response[String] = quickRequest
      .get(
        uri"https://api.open-meteo.com/v1/forecast?latitude=40.7143&longitude=-74.006&current_weather=true"
      )
      .send()
    val json = ujson.read(response.body)
    json.obj("current_weather")("temperature").num
  }
}

Next, change src/main/scala/example/Hello.scala as follows:

package example

import example.core.Weather

object Hello {
  def main(args: Array[String]): Unit = {
    val temp = Weather.temp()
    println(s"Hello! The current temperature in New York is $temp C.")
  }
}

Let’s run the app to see if it worked:

sbt:Hello> run
[info] compiling 1 Scala source to /tmp/foo-build/core/target/scala-2.13/classes ...
[info] compiling 1 Scala source to /tmp/foo-build/target/scala-2.13/classes ...
[info] running example.Hello
Hello! The current temperature in New York is 22.7 C.

Add sbt-native-packager plugin 

Using an editor, create project/plugins.sbt:

addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.9.4")

Next change build.sbt as follows to add JavaAppPackaging:

ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

val toolkitTest = "org.scala-lang" %% "toolkit-test" % "0.1.7"

lazy val hello = project
  .in(file("."))
  .aggregate(helloCore)
  .dependsOn(helloCore)
  .enablePlugins(JavaAppPackaging)
  .settings(
    name := "Hello",
    libraryDependencies += toolkitTest % Test,
    maintainer := "A Scala Dev!"
  )

lazy val helloCore = project
  .in(file("core"))
  .settings(
    name := "Hello Core",
    libraryDependencies += "org.scala-lang" %% "toolkit" % "0.1.7",
    libraryDependencies += toolkitTest % Test
  )

Reload and create a .zip distribution 

sbt:Hello> reload
...
sbt:Hello> dist
[info] Wrote /private/tmp/foo-build/target/scala-2.13/hello_2.13-0.1.0-SNAPSHOT.pom
[info] Main Scala API documentation to /tmp/foo-build/target/scala-2.13/api...
[info] Main Scala API documentation successful.
[info] Main Scala API documentation to /tmp/foo-build/core/target/scala-2.13/api...
[info] Wrote /tmp/foo-build/core/target/scala-2.13/hello-core_2.13-0.1.0-SNAPSHOT.pom
[info] Main Scala API documentation successful.
[success] All package validations passed
[info] Your package is ready in /tmp/foo-build/target/universal/hello-0.1.0-SNAPSHOT.zip

Here’s how you can run the packaged app:

$ /tmp/someother
$ cd /tmp/someother
$ unzip -o -d /tmp/someother /tmp/foo-build/target/universal/hello-0.1.0-SNAPSHOT.zip
$ ./hello-0.1.0-SNAPSHOT/bin/hello
Hello! The current temperature in New York is 22.7 C.

Dockerize your app 

Note that a Docker daemon will need to be running in order for this to work.

sbt:Hello> Docker/publishLocal
....
[info] Built image hello with tags [0.1.0-SNAPSHOT]

Here’s how to run the Dockerized app:

$ docker run hello:0.1.0-SNAPSHOT
Hello! The current temperature in New York is 22.7 C.

Set the version 

Change build.sbt as follows:

ThisBuild / version := "0.1.0"
ThisBuild / scalaVersion := "2.13.12"
ThisBuild / organization := "com.example"

val toolkitTest = "org.scala-lang" %% "toolkit-test" % "0.1.7"

lazy val hello = project
  .in(file("."))
  .aggregate(helloCore)
  .dependsOn(helloCore)
  .enablePlugins(JavaAppPackaging)
  .settings(
    name := "Hello",
    libraryDependencies += toolkitTest % Test,
    maintainer := "A Scala Dev!"
  )

lazy val helloCore = project
  .in(file("core"))
  .settings(
    name := "Hello Core",
    libraryDependencies += "org.scala-lang" %% "toolkit" % "0.1.7",
    libraryDependencies += toolkitTest % Test
  )

Switch scalaVersion temporarily 

sbt:Hello> ++3.3.1!
[info] Forcing Scala version to 3.3.1 on all projects.
[info] Reapplying settings...
[info] Set current project to Hello (in build file:/tmp/foo-build/)

Check the scalaVersion setting:

sbt:Hello> scalaVersion
[info] helloCore / scalaVersion
[info]  3.3.1
[info] scalaVersion
[info]  3.3.1

This setting will go away after reload.

Inspect the dist task 

To find out more about dist, try help and inspect.

sbt:Hello> help dist
Creates the distribution packages.
sbt:Hello> inspect dist

To call inspect recursively on the dependency tasks use inspect tree.

sbt:Hello> inspect tree dist
[info] dist = Task[java.io.File]
[info]   +-Universal / dist = Task[java.io.File]
....

Batch mode 

You can also run sbt in batch mode, passing sbt commands directly from the terminal.

$ sbt clean "testOnly HelloSuite"

Note: Running in batch mode requires JVM spinup and JIT each time, so your build will run much slower. For day-to-day coding, we recommend using the sbt shell or a continuous test like ~testQuick.

sbt new command 

You can use the sbt new command to quickly setup a simple “Hello world” build.

$ sbt new scala/scala-seed.g8
....
A minimal Scala project.

name [My Something Project]: hello

Template applied in ./hello

When prompted for the project name, type hello.

This will create a new project under a directory named hello.

Credits 

This page is based on the Essential sbt tutorial written by William “Scala William” Narmontas.

Directory structure 

This page assumes you’ve installed sbt and seen sbt by example.

Base directory 

In sbt’s terminology, the “base directory” is the directory containing the project. So if you created a project hello containing /tmp/foo-build/build.sbt as in the sbt by example, /tmp/foo-build is your base directory.

Source code 

sbt uses the same directory structure as Maven for source files by default (all paths are relative to the base directory):

src/
  main/
    resources/
       <files to include in main jar here>
    scala/
       <main Scala sources>
    scala-2.12/
       <main Scala 2.12 specific sources>
    java/
       <main Java sources>
  test/
    resources
       <files to include in test jar here>
    scala/
       <test Scala sources>
    scala-2.12/
       <test Scala 2.12 specific sources>
    java/
       <test Java sources>

Other directories in src/ will be ignored. Additionally, all hidden directories will be ignored.

Source code can be placed in the project’s base directory as hello/app.scala, which may be OK for small projects, though for normal projects people tend to keep the projects in the src/main/ directory to keep things neat. The fact that you can place *.scala source code in the base directory might seem like an odd trick, but this fact becomes relevant later.

sbt build definition files 

The build definition is described in build.sbt (actually any files named *.sbt) in the project’s base directory.

build.sbt

Build support files 

In addition to build.sbt, project directory can contain .scala files that define helper objects and one-off plugins. See organizing the build for more.

build.sbt
project/
  Dependencies.scala

You may see .sbt files inside project/ but they are not equivalent to .sbt files in the project’s base directory. Explaining this will come later, since you’ll need some background information first.

Build products 

Generated files (compiled classes, packaged jars, managed files, caches, and documentation) will be written to the target directory by default.

Configuring version control 

Your .gitignore (or equivalent for other version control systems) should contain:

target/

Note that this deliberately has a trailing / (to match only directories) and it deliberately has no leading / (to match project/target/ in addition to plain target/).

Running 

This page describes how to use sbt once you have set up your project. It assumes you’ve installed sbt and went through sbt by example.

sbt shell 

Run sbt in your project directory with no arguments:

$ sbt

Running sbt with no command line arguments starts sbt shell. sbt shell has a command prompt (with tab completion and history!).

For example, you could type compile at the sbt shell:

> compile

To compile again, press up arrow and then enter.

To run your program, type run.

To leave sbt shell, type exit or use Ctrl+D (Unix) or Ctrl+Z (Windows).

Batch mode 

You can also run sbt in batch mode, specifying a space-separated list of sbt commands as arguments. For sbt commands that take arguments, pass the command and arguments as one argument to sbt by enclosing them in quotes. For example,

$ sbt clean compile "testOnly TestA TestB"

In this example, testOnly has arguments, TestA and TestB. The commands will be run in sequence (clean, compile, then testOnly).

Note: Running in batch mode requires JVM spinup and JIT each time, so your build will run much slower. For day-to-day coding, we recommend using the sbt shell or Continuous build and test feature described below.

Beginning in sbt 0.13.16, using batch mode in sbt will issue an informational startup message,

$ sbt clean compile
[info] Executing in batch mode. For better performance use sbt's shell
...

It will only be triggered for sbt compile, and it can also be suppressed with suppressSbtShellNotification := true.

Continuous build and test 

To speed up your edit-compile-test cycle, you can ask sbt to automatically recompile or run tests whenever you save a source file.

Make a command run when one or more source files change by prefixing the command with ~. For example, in sbt shell try:

> ~testQuick

Press enter to stop watching for changes.

You can use the ~ prefix with either sbt shell or batch mode.

See Triggered Execution for more details.

Common commands 

Here are some of the most common sbt commands. For a more complete list, see Command Line Reference.

Tab completion 

sbt shell has tab completion, including at an empty prompt. A special sbt convention is that pressing tab once may show only a subset of most likely completions, while pressing it more times shows more verbose choices.

sbt shell history 

sbt shell remembers history even if you exit sbt and restart it. The easiest way to access history is to press the up arrow key to cycle through previously entered commands.

Note: Ctrl-R incrementally searches the history backwards.

Through JLine’s integration with the terminal environment, you can customize sbt shell by changing $HOME/.inputrc file. For example, the following settings in $HOME/.inputrc will allow up- and down-arrow to perform prefix-based search of the history.

"\e[A": history-search-backward
"\e[B": history-search-forward
"\e[C": forward-char
"\e[D": backward-char

sbt shell also supports the following commands:

IDE Integration 

While it’s possible to code Scala with just an editor and sbt, most programmers today use an Integrated Development Environment, or IDE for short. Two of the popular IDEs in Scala are Metals and IntelliJ IDEA, and they both integrate with sbt builds.

• Using sbt as Metals build server
• Importing to IntelliJ IDEA
• Using sbt as IntelliJ IDEA build server
• Using Neovim as Metals frontend

Using sbt as Metals build server 

Metals is an open source language server for Scala, which can act as the backend for VS Code and other editors that support LSP. Metals in turn supports different build servers including sbt via the Build Server Protocol (BSP).

To use Metals on VS Code:

1. Install Metals from Extensions tab:
   
2. Open a directory containing a build.sbt file.
3. From the menubar, run View > Command Palette… (Cmd-Shift-P on macOS) “Metals: Switch build server”, and select “sbt”
   
4. Once the import process is complete, open a Scala file to see that code completion works:
   

Use the following setting to opt-out some of the subprojects from BSP.

bspEnabled := false

When you make changes to the code and save them (Cmd-S on macOS), Metals will invoke sbt to do the actual building work.

Interactive debugging on VS Code 

1. Metals supports interactive debugging by setting break points in the code:
   
2. Interactive debugging can be started by right-clicking on an unit test, and selecting “Debug Test.” When the test hits a break point, you can inspect the values of the variables:
   

See Debugging page on VS Code documentation for more details on how to navigate an interactive debugging session.

Logging into sbt session 

While Metals uses sbt as the build server, we can also log into the same sbt session using a thin client.

• From Terminal section, type in sbt --client
  

This lets you log into the sbt session Metals has started. In there you can call testOnly and other tasks with the code already compiled.

Importing to IntelliJ IDEA 

IntelliJ IDEA is an IDE created by JetBrains, and the Community Edition is open source under Apache v2 license. IntelliJ integrates with many build tools, including sbt, to import the project. This is a more traditional approach that might be more reliable than using BSP approach.

To import a build to IntelliJ IDEA:

1. Install Scala plugin on the Plugins tab:
   
2. From Projects, open a directory containing a build.sbt file.
   
3. Once the import process is complete, open a Scala file to see that code completion works.

IntelliJ Scala plugin uses its own lightweight compilation engine to detect errors, which is fast but sometimes incorrect. Per compiler-based highlighting, IntelliJ can be configured to use the Scala compiler for error highlighting.

Interactive debugging with IntelliJ IDEA 

1. IntelliJ supports interactive debugging by setting break points in the code:
   
2. Interactive debugging can be started by right-clicking on an unit test, and selecting “Debug ‘<test name>‘.” 　　Alternatively, you can click the green “run” icon on the left part of the editor near the unit test. When the test hits a break point, you can inspect the values of the variables:
   

See Debug Code page on IntelliJ documentation for more details on how to navigate an interactive debugging session.

Using sbt as IntelliJ IDEA build server (advanced) 

Importing the build to IntelliJ means that you’re effectively using IntelliJ as the build tool and the compiler while you code (see also compiler-based highlighting). While many users are happy with the experience, depending on the code base some of the compilation errors may be false, it may not work well with plugins that generate sources, and generally you might want to code with the identical build semantics as sbt. Thankfully, modern IntelliJ supports alternative build servers including sbt via the Build Server Protocol (BSP).

The benefit of using BSP with IntelliJ is that you’re using sbt to do the actual build work, so if you are the kind of programmer who had sbt session up on the side, this avoids double compilation.

To use sbt as build server on IntelliJ:

1. Install Scala plugin on the Plugins tab.
2. To use the BSP approach, do not use Open button on the Project tab:
   
3. From menubar, click New > “Project From Existing Sources”, or Find Action (Cmd-Shift-P on macOS) and type “Existing” to find “Import Project From Existing Sources”:
   
4. Open a build.sbt file. Select BSP when prompted:
   
5. Select sbt (recommended) as the tool to import the BSP workspace:
   
6. Once the import process is complete, open a Scala file to see that code completion works:
   

Use the following setting to opt-out some of the subprojects from BSP.

bspEnabled := false

• Open Preferences, search BSP and check “build automatically on file save”, and uncheck “export sbt projects to Bloop before import”:
  

When you make changes to the code and save them (Cmd-S on macOS), IntelliJ will invoke sbt to do the actual building work.

See also Igal Tabachnik’s Using BSP effectively in IntelliJ and Scala for more details.

Logging into sbt session 

We can also log into the existing sbt session using the thin client.

• From Terminal section, type in sbt --client

This lets you log into the sbt session IntelliJ has started. In there you can call testOnly and other tasks with the code already compiled.

Using Neovim as Metals frontend (advanced) 

Neovim is a modern fork of Vim that supports LSP out-of-box, which means it can be configured as a frontend for Metals.

Chris Kipp, who is a maintainer of Metals, created nvim-metals plugin that provides comprehensive Metals support on Neovim. To install nvim-metals, create lsp.lua under $XDG_CONFIG_HOME/nvim/lua/ based on Chris’s lsp.lua and adjust to your preference. For example, comment out its plugins section and load the listed plugins using the plugin manager of your choice such as vim-plug.

In init.vim, the file can be loaded as:

lua << END
require('lsp')
END

Per lsp.lua, g:metals_status should be displayed on the status line, which can be done using lualine.nvim etc.

1. Next, open a Scala file in an sbt build using Neovim.
2. Run :MetalsInstall when prompted.
3. Run :MetalsStartServer.
4. If the status line is set up, you should see something like “Connecting to sbt” or “Indexing.”
   
5. Code completion works when you’re in Insert mode, and you can tab through the candidates:
   

• A build is triggered upon saving changes, and compilation errors are displayed inline:
  

Go to definition 

1. You can jump to definition of the symbol under cursor by using gD (exact keybinding can be customized):
   
2. Use Ctrl-O to return to the old buffer.

Hover 

• To display the type information of the symbol under cursor, like hovering, use K in Normal mode:
  

Listing diagnostics 

1. To list all compilation errors and warnings, use <leader>aa:
   
2. Since this is in the standard quickfix list, you can use the command such as :cnext and :cprev to nagivate through the errors and warnings.
3. To list just the errors, use <leader>ae.

Interactive debugging with Neovim 

1. Thanks to nvim-dap, Neovim supports interactive debugging. Set break points in the code using <leader>dt:
   
2. Nagivate to a unit test, confirm that it’s built by hovering (K), and then “debug continue” (<leader>dc) to start a debugger. Choose “1: RunOrTest” when prompted.
3. When the test hits a break point, you can inspect the values of the variables by debug hovering (<leader>dK):
   
4. “debug continue” (<leader>dc) again to end the session.

See nvim-metals regarding further details.

Logging into sbt session 

We can also log into the existing sbt session using the thin client.

1. In a new vim window type :terminal to start the built-in terminal.
2. Type in sbt --client
   

Even though it’s inside Neovim, tab completion etc works fine inside.

Build definition 

This page describes sbt build definitions, including some “theory” and the syntax of build.sbt. It assumes you have installed a recent version of sbt, such as sbt 1.9.8, know how to use sbt, and have read the previous pages in the Getting Started Guide.

This page discusses the build.sbt build definition.

Specifying the sbt version 

As part of your build definition you will specify the version of sbt that your build uses. This allows people with different versions of the sbt launcher to build the same projects with consistent results. To do this, create a file named project/build.properties that specifies the sbt version as follows:

sbt.version=1.9.8

If the required version is not available locally, the sbt launcher will download it for you. If this file is not present, the sbt launcher will choose an arbitrary version, which is discouraged because it makes your build non-portable.

What is a build definition? 

A build definition is defined in build.sbt, and it consists of a set of projects (of type Project). Because the term project can be ambiguous, we often call it a subproject in this guide.

For instance, in build.sbt you define the subproject located in the current directory like this:

lazy val root = (project in file("."))
  .settings(
    name := "Hello",
    scalaVersion := "2.12.7"
  )

Each subproject is configured by key-value pairs.

For example, one key is name and it maps to a string value, the name of your subproject. The key-value pairs are listed under the .settings(...) method as follows:

lazy val root = (project in file("."))
  .settings(
    name := "Hello",
    scalaVersion := "2.12.7"
  )

How build.sbt defines settings 

build.sbt defines subprojects, which holds a sequence of key-value pairs called setting expressions using build.sbt domain-specific language(DSL).

ThisBuild / organization := "com.example"
ThisBuild / scalaVersion := "2.12.18"
ThisBuild / version      := "0.1.0-SNAPSHOT"

lazy val root = (project in file("."))
  .settings(
    name := "hello"
  )

Let’s take a closer look at the build.sbt DSL:

Each entry is called a setting expression. Some among them are also called task expressions. We will see more on the difference later in this page.

A setting expression consists of three parts:

1. Left-hand side is a key.
2. Operator, which in this case is :=
3. Right-hand side is called the body, or the setting body.

On the left-hand side, name, version, and scalaVersion are keys. A key is an instance of SettingKey[T], TaskKey[T], or InputKey[T] where T is the expected value type. The kinds of key are explained below.

Because key name is typed to SettingKey[String], the := operator on name is also typed specifically to String. If you use the wrong value type, the build definition will not compile:

lazy val root = (project in file("."))
  .settings(
    name := 42  // will not compile
  )

build.sbt may also be interspersed with vals, lazy vals, and defs. Top-level objects and classes are not allowed in build.sbt. Those should go in the project/ directory as Scala source files.

Keys 

Types 

There are three flavors of key:

• SettingKey[T]: a key for a value evaluated only once (the value is computed when loading the subproject, and kept around).
• TaskKey[T]: a key for a value, called a task, that is evaluated each time it’s referred to (similarly to a scala function), potentially with side effects.
• InputKey[T]: a key for a task that has command line arguments as input. Check out Input Tasks for more details.

Built-in Keys 

The built-in keys are just fields in an object called Keys. A build.sbt implicitly has an import sbt.Keys._, so sbt.Keys.name can be referred to as name.

Custom Keys 

Custom keys may be defined with their respective creation methods: settingKey, taskKey, and inputKey. Each method expects the type of the value associated with the key as well as a description. The name of the key is taken from the val the key is assigned to. For example, to define a key for a new task called hello,

lazy val hello = taskKey[Unit]("An example task")

Here we have used the fact that an .sbt file can contain vals and defs in addition to settings. All such definitions are evaluated before settings regardless of where they are defined in the file.

Note: Typically, lazy vals are used instead of vals to avoid initialization order problems.

Task vs Setting keys 

A TaskKey[T] is said to define a task. Tasks are operations such as compile or package. They may return Unit (Unit is void for Scala), or they may return a value related to the task, for example package is a TaskKey[File] and its value is the jar file it creates.

Each time you start a task execution, for example by typing compile at the interactive sbt prompt, sbt will re-run any tasks involved exactly once.

sbt’s key-value pairs describing the subproject can keep around a fixed string value for a setting such as name, but it has to keep around some executable code for a task such as compile — even if that executable code eventually returns a string, it has to be re-run every time.

A given key always refers to either a task or a plain setting. That is, “taskiness” (whether to re-run each time) is a property of the key, not the value.

Listing all available setting keys and task keys 

The list of settings keys that currently exist in your build definition can be obtained by typing settings or settings -v at the sbt prompt.

Likewise, the list of tasks keys currently defined can be obtained by typing tasks or tasks -v. You can also have a look at Command Line Reference for a discussion on built-in tasks commonly used at the sbt prompt.
A key will be printed in the resulting list if:

• it’s built-in sbt (like name or scalaVersion in the examples above)
• you created it as a custom key
• you imported a plugin that brought it into the build definition.

You can also type help <key> at the sbt prompt for more information.

Defining tasks and settings 

Using :=, you can assign a value to a setting and a computation to a task. For a setting, the value will be computed once at project load time. For a task, the computation will be re-run each time the task is executed.

For example, to implement the hello task from the previous section:

lazy val hello = taskKey[Unit]("An example task")

lazy val root = (project in file("."))
  .settings(
    hello := { println("Hello!") }
  )

We already saw an example of defining settings when we defined the project’s name,

lazy val root = (project in file("."))
  .settings(
    name := "hello"
  )

Types for tasks and settings 

From a type-system perspective, the Setting created from a task key is slightly different from the one created from a setting key. taskKey := 42 results in a Setting[Task[T]] while settingKey := 42 results in a Setting[T]. For most purposes this makes no difference; the task key still creates a value of type T when the task executes.

The T vs. Task[T] type difference has this implication: a setting can’t depend on a task, because a setting is evaluated only once on project load and is not re-run. More on this in task graph.

Keys in sbt shell 

In sbt shell, you can type the name of any task to execute that task. This is why typing compile runs the compile task. compile is a task key.

If you type the name of a setting key rather than a task key, the value of the setting key will be displayed. Typing a task key name executes the task but doesn’t display the resulting value; to see a task’s result, use show <task name> rather than plain <task name>. The convention for keys names is to use camelCase so that the command line name and the Scala identifiers are the same.

To learn more about any key, type inspect <keyname> at the sbt interactive prompt. Some of the information inspect displays won’t make sense yet, but at the top it shows you the setting’s value type and a brief description of the setting.

Imports in build.sbt 

You can place import statements at the top of build.sbt; they need not be separated by blank lines.

There are some implied default imports, as follows:

import sbt._
import Keys._

(In addition, if you have auto plugins, the names marked under autoImport will be imported.)

Bare .sbt build definition 

The settings can be written directly into the build.sbt file instead of putting them inside a .settings(...) call. We call this the “bare style.”

ThisBuild / version := "1.0"
ThisBuild / scalaVersion := "2.12.18"

This syntax is recommended for ThisBuild scoped settings and adding plugins. See later section about the scoping and the plugins.

Adding library dependencies 

To depend on third-party libraries, there are two options. The first is to drop jars in lib/ (unmanaged dependencies) and the other is to add managed dependencies, which will look like this in build.sbt:

val derby = "org.apache.derby" % "derby" % "10.4.1.3"

ThisBuild / organization := "com.example"
ThisBuild / scalaVersion := "2.12.18"
ThisBuild / version      := "0.1.0-SNAPSHOT"

lazy val root = (project in file("."))
  .settings(
    name := "Hello",
    libraryDependencies += derby
  )

This is how you add a managed dependency on the Apache Derby library, version 10.4.1.3.

The libraryDependencies key involves two complexities: += rather than :=, and the % method. += appends to the key’s old value rather than replacing it, this is explained in Task Graph. The % method is used to construct an Ivy module ID from strings, explained in Library dependencies.

We’ll skip over the details of library dependencies until later in the Getting Started Guide. There’s a whole page covering it later on.

Multi-project builds 

This page introduces multiple subprojects in a single build.

Please read the earlier pages in the Getting Started Guide first, in particular you need to understand build.sbt before reading this page.

Multiple subprojects 

It can be useful to keep multiple related subprojects in a single build, especially if they depend on one another and you tend to modify them together.

Each subproject in a build has its own source directories, generates its own jar file when you run package, and in general works like any other project.

A project is defined by declaring a lazy val of type Project. For example, :

lazy val util = (project in file("util"))

lazy val core = (project in file("core"))

The name of the val is used as the subproject’s ID, which is used to refer to the subproject at the sbt shell.

Optionally the base directory may be omitted if it’s the same as the name of the val.

lazy val util = project

lazy val core = project

Build-wide settings 

To factor out common settings across multiple subprojects, define the settings scoped to ThisBuild. ThisBuild acts as a special subproject name that you can use to define default value for the build. When you define one or more subprojects, and when the subproject does not define scalaVersion key, it will look for ThisBuild / scalaVersion.

The limitation is that the right-hand side needs to be a pure value or settings scoped to Global or ThisBuild, and there are no default settings scoped to subprojects. (See Scopes)

ThisBuild / organization := "com.example"
ThisBuild / version      := "0.1.0-SNAPSHOT"
ThisBuild / scalaVersion := "2.12.18"

lazy val core = (project in file("core"))
  .settings(
    // other settings
  )

lazy val util = (project in file("util"))
  .settings(
    // other settings
  )

Now we can bump up version in one place, and it will be reflected across subprojects when you reload the build.

Common settings 

Another way to factor out common settings across multiple projects is to create a sequence named commonSettings and call settings method on each project.

lazy val commonSettings = Seq(
  target := { baseDirectory.value / "target2" }
)

lazy val core = (project in file("core"))
  .settings(
    commonSettings,
    // other settings
  )

lazy val util = (project in file("util"))
  .settings(
    commonSettings,
    // other settings
  )

Dependencies 

Projects in the build can be completely independent of one another, but usually they will be related to one another by some kind of dependency. There are two types of dependencies: aggregate and classpath.

Aggregation 

Aggregation means that running a task on the aggregate project will also run it on the aggregated projects. For example,

lazy val root = (project in file("."))
  .aggregate(util, core)

lazy val util = (project in file("util"))

lazy val core = (project in file("core"))

In the above example, the root project aggregates util and core. Start up sbt with two subprojects as in the example, and try compile. You should see that all three projects are compiled.

In the project doing the aggregating, the root project in this case, you can control aggregation per-task. For example, to avoid aggregating the update task:

lazy val root = (project in file("."))
  .aggregate(util, core)
  .settings(
    update / aggregate := false
  )

[...]

update / aggregate is the aggregate key scoped to the update task. (See scopes.)

Note: aggregation will run the aggregated tasks in parallel and with no defined ordering between them.

Classpath dependencies 

A project may depend on code in another project. This is done by adding a dependsOn method call. For example, if core needed util on its classpath, you would define core as:

lazy val core = project.dependsOn(util)

Now code in core can use classes from util. This also creates an ordering between the projects when compiling them; util must be updated and compiled before core can be compiled.

To depend on multiple projects, use multiple arguments to dependsOn, like dependsOn(bar, baz).

Per-configuration classpath dependencies 

core dependsOn(util) means that the compile configuration in core depends on the compile configuration in util. You could write this explicitly as dependsOn(util % "compile->compile").

The -> in "compile->compile" means “depends on” so "test->compile" means the test configuration in core would depend on the compile configuration in util.

Omitting the ->config part implies ->compile, so dependsOn(util % "test") means that the test configuration in core depends on the Compile configuration in util.

A useful declaration is "test->test" which means test depends on test. This allows you to put utility code for testing in util/src/test/scala and then use that code in core/src/test/scala, for example.

You can have multiple configurations for a dependency, separated by semicolons. For example, dependsOn(util % "test->test;compile->compile").

Inter-project dependencies 

On extremely large projects with many files and many subprojects, sbt can perform less optimally at continuously watching files that have changed and use a lot of disk and system I/O.

sbt has trackInternalDependencies and exportToInternal settings. These can be used to control whether to trigger compilation of a dependent subprojects when you call compile. Both keys will take one of three values: TrackLevel.NoTracking, TrackLevel.TrackIfMissing, and TrackLevel.TrackAlways. By default they are both set to TrackLevel.TrackAlways.

When trackInternalDependencies is set to TrackLevel.TrackIfMissing, sbt will no longer try to compile internal (inter-project) dependencies automatically, unless there are no *.class files (or JAR file when exportJars is true) in the output directory.

When the setting is set to TrackLevel.NoTracking, the compilation of internal dependencies will be skipped. Note that the classpath will still be appended, and dependency graph will still show them as dependencies. The motivation is to save the I/O overhead of checking for the changes on a build with many subprojects during development. Here’s how to set all subprojects to TrackIfMissing.

ThisBuild / trackInternalDependencies := TrackLevel.TrackIfMissing
ThisBuild / exportJars := true

lazy val root = (project in file("."))
  .aggregate(....)

The exportToInternal setting allows the dependee subprojects to opt out of the internal tracking, which might be useful if you want to track most subprojects except for a few. The intersection of the trackInternalDependencies and exportToInternal settings will be used to determine the actual track level. Here’s an example to opt-out one project:

lazy val dontTrackMe = (project in file("dontTrackMe"))
  .settings(
    exportToInternal := TrackLevel.NoTracking
  )

Default root project 

If a project is not defined for the root directory in the build, sbt creates a default one that aggregates all other projects in the build.

Because project hello-foo is defined with base = file("foo"), it will be contained in the subdirectory foo. Its sources could be directly under foo, like foo/Foo.scala, or in foo/src/main/scala. The usual sbt directory structure applies underneath foo with the exception of build definition files.

Navigating projects interactively 

At the sbt interactive prompt, type projects to list your projects and project <projectname> to select a current project. When you run a task like compile, it runs on the current project. So you don’t necessarily have to compile the root project, you could compile only a subproject.

You can run a task in another project by explicitly specifying the project ID, such as subProjectID/compile.

Common code 

The definitions in .sbt files are not visible in other .sbt files. In order to share code between .sbt files, define one or more Scala files in the project/ directory of the build root.

See organizing the build for details.

Appendix: Subproject build definition files 

Any .sbt files in foo, say foo/build.sbt, will be merged with the build definition for the entire build, but scoped to the hello-foo project.

If your whole project is in hello, try defining a different version (version := "0.6") in hello/build.sbt, hello/foo/build.sbt, and hello/bar/build.sbt. Now show version at the sbt interactive prompt. You should get something like this (with whatever versions you defined):

> show version
[info] hello-foo/*:version
[info]  0.7
[info] hello-bar/*:version
[info]  0.9
[info] hello/*:version
[info]  0.5

hello-foo/*:version was defined in hello/foo/build.sbt, hello-bar/*:version was defined in hello/bar/build.sbt, and hello/*:version was defined in hello/build.sbt. Remember the syntax for scoped keys. Each version key is scoped to a project, based on the location of the build.sbt. But all three build.sbt are part of the same build definition.

Style choices:

• Each subproject’s settings can go into *.sbt files in the base directory of that project, while the root build.sbt declares only minimum project declarations in the form of lazy val foo = (project in file("foo")) without the settings.
• We recommend putting all project declarations and settings in the root build.sbt file in order to keep all build definition under a single file. However, it’s up to you.

Note: You cannot have a project subdirectory or project/*.scala files in the sub-projects. foo/project/Build.scala would be ignored.

Task graph 

Continuing from build definition, this page explains build.sbt definition in more detail.

Rather than thinking of settings as key-value pairs, a better analogy would be to think of it as a directed acyclic graph (DAG) of tasks where the edges denote happens-before. Let’s call this the task graph.

Terminology 

Let’s review the key terms before we dive in.

• Setting/Task expression: entry inside .settings(...).
• Key: Left hand side of a setting expression. It could be a SettingKey[A], a TaskKey[A], or an InputKey[A].
• Setting: Defined by a setting expression with SettingKey[A]. The value is calculated once during load.
• Task: Defined by a task expression with TaskKey[A]. The value is calculated each time it is invoked.

Declaring dependency to other tasks 

In build.sbt DSL, we use .value method to express the dependency to another task or setting. The value method is special and may only be called in the argument to := (or, += or ++=, which we’ll see later).

As a first example, consider defining the scalacOptions that depends on update and clean tasks. Here are the definitions of these keys (from Keys).

Note: The values calculated below are nonsensical for scalaOptions, and it’s just for demonstration purpose only:

val scalacOptions = taskKey[Seq[String]]("Options for the Scala compiler.")
val update = taskKey[UpdateReport]("Resolves and optionally retrieves dependencies, producing a report.")
val clean = taskKey[Unit]("Deletes files produced by the build, such as generated sources, compiled classes, and task caches.")

Here’s how we can rewire scalacOptions:

scalacOptions := {
  val ur = update.value  // update task happens-before scalacOptions
  val x = clean.value    // clean task happens-before scalacOptions
  // ---- scalacOptions begins here ----
  ur.allConfigurations.take(3)
}

update.value and clean.value declare task dependencies, whereas ur.allConfigurations.take(3) is the body of the task.

.value is not a normal Scala method call. build.sbt DSL uses a macro to lift these outside of the task body. Both update and clean tasks are completed by the time task engine evaluates the opening { of scalacOptions regardless of which line it appears in the body.

See the following example:

ThisBuild / organization := "com.example"
ThisBuild / scalaVersion := "2.12.18"
ThisBuild / version      := "0.1.0-SNAPSHOT"

lazy val root = (project in file("."))
  .settings(
    name := "Hello",
    scalacOptions := {
      val out = streams.value // streams task happens-before scalacOptions
      val log = out.log
      log.info("123")
      val ur = update.value   // update task happens-before scalacOptions
      log.info("456")
      ur.allConfigurations.take(3)
    }
  )

Next, from sbt shell type scalacOptions:

> scalacOptions
[info] Updating {file:/xxx/}root...
[info] Resolving jline#jline;2.14.1 ...
[info] Done updating.
[info] 123
[info] 456
[success] Total time: 0 s, completed Jan 2, 2017 10:38:24 PM

Even though val ur = ... appears in between log.info("123") and log.info("456") the evaluation of update task happens before either of them.

Here’s another example:

ThisBuild / organization := "com.example"
ThisBuild / scalaVersion := "2.12.18"
ThisBuild / version      := "0.1.0-SNAPSHOT"

lazy val root = (project in file("."))
  .settings(
    name := "Hello",
    scalacOptions := {
      val ur = update.value  // update task happens-before scalacOptions
      if (false) {
        val x = clean.value  // clean task happens-before scalacOptions
      }
      ur.allConfigurations.take(3)
    }
  )

Next, from sbt shell type run then scalacOptions:

> run
[info] Updating {file:/xxx/}root...
[info] Resolving jline#jline;2.14.1 ...
[info] Done updating.
[info] Compiling 1 Scala source to /Users/eugene/work/quick-test/task-graph/target/scala-2.12/classes...
[info] Running example.Hello
hello
[success] Total time: 0 s, completed Jan 2, 2017 10:45:19 PM
> scalacOptions
[info] Updating {file:/xxx/}root...
[info] Resolving jline#jline;2.14.1 ...
[info] Done updating.
[success] Total time: 0 s, completed Jan 2, 2017 10:45:23 PM

Now if you check for target/scala-2.12/classes/, it won’t exist because clean task has run even though it is inside the if (false).

Another important thing to note is that there’s no guarantee about the ordering of update and clean tasks. They might run update then clean, clean then update, or both in parallel.

Inlining .value calls 

As explained above, .value is a special method that is used to express the dependency to other tasks and settings. Until you’re familiar with build.sbt, we recommend you put all .value calls at the top of the task body.

However, as you get more comfortable, you might wish to inline the .value calls because it could make the task/setting more concise, and you don’t have to come up with variable names.

We’ve inlined a few examples:

scalacOptions := {
  val x = clean.value
  update.value.allConfigurations.take(3)
}

Note whether .value calls are inlined, or placed anywhere in the task body, they are still evaluated before entering the task body.

Inspecting the task 

In the above example, scalacOptions has a dependency on update and clean tasks. If you place the above in build.sbt and run the sbt interactive console, then type inspect scalacOptions, you should see (in part):

> inspect scalacOptions
[info] Task: scala.collection.Seq[java.lang.String]
[info] Description:
[info]  Options for the Scala compiler.
....
[info] Dependencies:
[info]  *:clean
[info]  *:update
....

This is how sbt knows which tasks depend on which other tasks.

For example, if you inspect tree compile you’ll see it depends on another key incCompileSetup, which it in turn depends on other keys like dependencyClasspath. Keep following the dependency chains and magic happens.

> inspect tree compile
[info] compile:compile = Task[sbt.inc.Analysis]
[info]   +-compile:incCompileSetup = Task[sbt.Compiler$IncSetup]
[info]   | +-*/*:skip = Task[Boolean]
[info]   | +-compile:compileAnalysisFilename = Task[java.lang.String]
[info]   | | +-*/*:crossPaths = true
[info]   | | +-{.}/*:scalaBinaryVersion = 2.12
[info]   | |
[info]   | +-*/*:compilerCache = Task[xsbti.compile.GlobalsCache]
[info]   | +-*/*:definesClass = Task[scala.Function1[java.io.File, scala.Function1[java.lang.String, Boolean]]]
[info]   | +-compile:dependencyClasspath = Task[scala.collection.Seq[sbt.Attributed[java.io.File]]]
[info]   | | +-compile:dependencyClasspath::streams = Task[sbt.std.TaskStreams[sbt.Init$ScopedKey[_ <: Any]]]
[info]   | | | +-*/*:streamsManager = Task[sbt.std.Streams[sbt.Init$ScopedKey[_ <: Any]]]
[info]   | | |
[info]   | | +-compile:externalDependencyClasspath = Task[scala.collection.Seq[sbt.Attributed[java.io.File]]]
[info]   | | | +-compile:externalDependencyClasspath::streams = Task[sbt.std.TaskStreams[sbt.Init$ScopedKey[_ <: Any]]]
[info]   | | | | +-*/*:streamsManager = Task[sbt.std.Streams[sbt.Init$ScopedKey[_ <: Any]]]
[info]   | | | |
[info]   | | | +-compile:managedClasspath = Task[scala.collection.Seq[sbt.Attributed[java.io.File]]]
[info]   | | | | +-compile:classpathConfiguration = Task[sbt.Configuration]
[info]   | | | | | +-compile:configuration = compile
[info]   | | | | | +-*/*:internalConfigurationMap = <function1>
[info]   | | | | | +-*:update = Task[sbt.UpdateReport]
[info]   | | | | |
....

When you type compile sbt automatically performs an update, for example. It Just Works because the values required as inputs to the compile computation require sbt to do the update computation first.

In this way, all build dependencies in sbt are automatic rather than explicitly declared. If you use a key’s value in another computation, then the computation depends on that key.

Defining a task that depends on other settings 

scalacOptions is a task key. Let’s say it’s been set to some values already, but you want to filter out "-Xfatal-warnings" and "-deprecation" for non-2.12.

lazy val root = (project in file("."))
  .settings(
    name := "Hello",
    organization := "com.example",
    scalaVersion := "2.12.18",
    version := "0.1.0-SNAPSHOT",
    scalacOptions := List("-encoding", "utf8", "-Xfatal-warnings", "-deprecation", "-unchecked"),
    scalacOptions := {
      val old = scalacOptions.value
      scalaBinaryVersion.value match {
        case "2.12" => old
        case _      => old filterNot (Set("-Xfatal-warnings", "-deprecation").apply)
      }
    }
  )

Here’s how it should look on the sbt shell:

> show scalacOptions
[info] * -encoding
[info] * utf8
[info] * -Xfatal-warnings
[info] * -deprecation
[info] * -unchecked
[success] Total time: 0 s, completed Jan 2, 2017 11:44:44 PM
> ++2.11.8!
[info] Forcing Scala version to 2.11.8 on all projects.
[info] Reapplying settings...
[info] Set current project to Hello (in build file:/xxx/)
> show scalacOptions
[info] * -encoding
[info] * utf8
[info] * -unchecked
[success] Total time: 0 s, completed Jan 2, 2017 11:44:51 PM

Next, take these two keys (from Keys):

val scalacOptions = taskKey[Seq[String]]("Options for the Scala compiler.")
val checksums = settingKey[Seq[String]]("The list of checksums to generate and to verify for dependencies.")

Note: scalacOptions and checksums have nothing to do with each other. They are just two keys with the same value type, where one is a task.

It is possible to compile a build.sbt that aliases scalacOptions to checksums, but not the other way. For example, this is allowed:

// The scalacOptions task may be defined in terms of the checksums setting
scalacOptions := checksums.value

There is no way to go the other direction. That is, a setting key can’t depend on a task key. That’s because a setting key is only computed once on project load, so the task would not be re-run every time, and tasks expect to re-run every time.

// Bad example: The checksums setting cannot be defined in terms of the scalacOptions task!
checksums := scalacOptions.value

Defining a setting that depends on other settings 

In terms of the execution timing, we can think of the settings as a special tasks that evaluate during loading time.

Consider defining the project organization to be the same as the project name.

// name our organization after our project (both are SettingKey[String])
organization := name.value

Here’s a realistic example. This rewires Compile / scalaSource key to a different directory only when scalaBinaryVersion is "2.11".

Compile / scalaSource := {
  val old = (Compile / scalaSource).value
  scalaBinaryVersion.value match {
    case "2.11" => baseDirectory.value / "src-2.11" / "main" / "scala"
    case _      => old
  }
}

What’s the point of the build.sbt DSL? 

We use the build.sbt domain-specific language(DSL) to construct a DAG of settings and tasks. The setting expressions encode settings, tasks and the dependencies among them.

This structure is common to Make (1976), Ant (2000), and Rake (2003).

Intro to Make 

The basic Makefile syntax looks like the following:

target: dependencies
[tab] system command1
[tab] system command2

Given a target (the default target is named all),

1. Make checks if the target’s dependencies have been built, and builds any of the dependencies that hasn’t been built yet.
2. Make runs the system commands in order.

Let’s take a look at a Makefile:

CC=g++
CFLAGS=-Wall

all: hello

hello: main.o hello.o
    $(CC) main.o hello.o -o hello

%.o: %.cpp
    $(CC) $(CFLAGS) -c $< -o $@

Running make, it will by default pick the target named all. The target lists hello as its dependency, which hasn’t been built yet, so Make will build hello.

Next, Make checks if the hello target’s dependencies have been built yet. hello lists two targets: main.o and hello.o. Once those targets are created using the last pattern matching rule, only then the system command is executed to link main.o and hello.o to hello.

If you’re just running make, you can focus on what you want as the target, and the exact timing and commands necessary to build the intermediate products are figured out by Make. We can think of this as dependency-oriented programming, or flow-based programming. Make is actually considered a hybrid system because while the DSL describes the task dependencies, the actions are delegated to system commands.

Rake 

This hybridity is continued for Make successors such as Ant, Rake, and sbt. Take a look at the basic syntax for Rakefile:

task name: [:prereq1, :prereq2] do |t|
  # actions (may reference prereq as t.name etc)
end

The breakthrough made with Rake was that it used a programming language to describe the actions instead of the system commands.

Benefits of hybrid flow-based programming 

There are several motivation to organizing the build this way.

First is de-duplication. With flow-based programming, a task is executed only once even when it is depended by multiple tasks. For example, even when multiple tasks along the task graph depend on Compile / compile, the compilation will be executed exactly once.

Second is parallel processing. Using the task graph, the task engine can schedule mutually non-dependent tasks in parallel.

Third is the separation of concern and the flexibility. The task graph lets the build user wire the tasks together in different ways, while sbt and plugins can provide various features such as compilation and library dependency management as functions that can be reused.

Summary 

The core data structure of the build definition is a DAG of tasks, where the edges denote happens-before relationships. build.sbt is a DSL designed to express dependency-oriented programming, or flow-based programming, similar to Makefile and Rakefile.

The key motivation for the flow-based programming is de-duplication, parallel processing, and customizability.

Scopes 

This page describes scopes. It assumes you’ve read and understood the previous pages, build definition and task graph.

The whole story about keys 

Previously we pretended that a key like name corresponded to one entry in sbt’s map of key-value pairs. This was a simplification.

In truth, each key can have an associated value in more than one context, called a scope.

Some concrete examples:

• if you have multiple projects (also called subprojects) in your build definition, a key can have a different value in each project.
• the compile key may have a different value for your main sources and your test sources, if you want to compile them differently.
• the packageOptions key (which contains options for creating jar packages) may have different values when packaging class files (packageBin) or packaging source code (packageSrc).

There is no single value for a given key name, because the value may differ according to scope.

However, there is a single value for a given scoped key.

If you think about sbt processing a list of settings to generate a key-value map describing the project, as discussed earlier, the keys in that key-value map are scoped keys. Each setting defined in the build definition (for example in build.sbt) applies to a scoped key as well.

Often the scope is implied or has a default, but if the defaults are wrong, you’ll need to mention the desired scope in build.sbt.

Scope axes 

A scope axis is a type constructor similar to Option[A], that is used to form a component in a scope.

There are three scope axes:

• The subproject axis
• The dependency configuration axis
• The task axis

If you’re not familiar with the notion of axis, we can think of the RGB color cube as an example:

In the RGB color model, all colors are represented by a point in the cube whose axes correspond to red, green, and blue components encoded by a number. Similarly, a full scope in sbt is formed by a tuple of a subproject, a configuration, and a task value:

projA / Compile / console / scalacOptions

This is the slash syntax, introduced in sbt 1.1, for:

scalacOptions in (
  Select(projA: Reference),
  Select(Compile: ConfigKey),
  Select(console.key)
)

Scoping by the subproject axis 

If you put multiple projects in a single build, each project needs its own settings. That is, keys can be scoped according to the project.

The project axis can also be set to ThisBuild, which means the “entire build”, so a setting applies to the entire build rather than a single project. Build-level settings are often used as a fallback when a project doesn’t define a project-specific setting. We will discuss more on build-level settings later in this page.

Scoping by the configuration axis 

A dependency configuration (or “configuration” for short) defines a graph of library dependencies, potentially with its own classpath, sources, generated packages, etc. The dependency configuration concept comes from Ivy, which sbt used to use for managed dependencies Library Dependencies, and from MavenScopes.

Some configurations you’ll see in sbt:

• Compile which defines the main build (src/main/scala).
• Test which defines how to build tests (src/test/scala).
• Runtime which defines the classpath for the run task.

By default, all the keys associated with compiling, packaging, and running are scoped to a configuration and therefore may work differently in each configuration. The most obvious examples are the task keys compile, package, and run; but all the keys which affect those keys (such as sourceDirectories or scalacOptions or fullClasspath) are also scoped to the configuration.

Another thing to note about a configuration is that it can extend other configurations. The following figure shows the extension relationship among the most common configurations.

Test and IntegrationTest extends Runtime; Runtime extends Compile; CompileInternal extends Compile, Optional, and Provided.

Scoping by Task axis 

Settings can affect how a task works. For example, the packageSrc task is affected by the packageOptions setting.

To support this, a task key (such as packageSrc) can be a scope for another key (such as packageOptions).

The various tasks that build a package (packageSrc, packageBin, packageDoc) can share keys related to packaging, such as artifactName and packageOptions. Those keys can have distinct values for each packaging task.

Zero scope component 

Each scope axis can be filled in with an instance of the axis type (analogous to Some(_)), or the axis can be filled in with the special value Zero. So we can think of Zero as None.

Zero is a universal fallback for all scope axes, but its direct use should be reserved to sbt and plugin authors in most cases.

Global is a scope that sets Zero to all axes: Zero / Zero / Zero. In other words, Global / someKey is a shorthand for Zero / Zero / Zero / someKey.

Referring to scopes in a build definition 

If you create a setting in build.sbt with a bare key, it will be scoped to (current subproject / configuration Zero / task Zero):

lazy val root = (project in file("."))
  .settings(
    name := "hello"
  )

Run sbt and inspect name to see that it’s provided by ProjectRef(uri("file:/private/tmp/hello/"), "root") / name, that is, the project is ProjectRef(uri("file:/Users/xxx/hello/"), "root"), and neither configuration nor task scope are shown (which means Zero).

A bare key on the right hand side is also scoped to (current subproject / configuration Zero / task Zero):

organization := name.value

The types of any of the scope axes have been method enriched to have a / operator. The argument to / can be a key or another scope axis. So for example, though there’s no good reason to do this, you could have an instance of the name key scoped to the Compile configuration:

Compile / name := "hello"

or you could set the name scoped to the packageBin task (pointless! just an example):

packageBin / name := "hello"

or you could set the name with multiple scope axes, for example in the packageBin task in the Compile configuration:

Compile / packageBin / name := "hello"

or you could use Global:

// same as Zero / Zero / Zero / concurrentRestrictions
Global / concurrentRestrictions := Seq(
  Tags.limitAll(1)
)

(Global / concurrentRestrictions implicitly converts to Zero / Zero / Zero / concurrentRestrictions, setting all axes to Zero scope component; the task and configuration are already Zero by default, so here the effect is to make the project Zero, that is, define Zero / Zero / Zero / concurrentRestrictions rather than ProjectRef(uri("file:/tmp/hello/"), "root") / Zero / Zero / concurrentRestrictions)

Referring to scoped keys from the sbt shell 

On the command line and in the sbt shell, sbt displays (and parses) scoped keys like this:

ref / Config / intask / key

• ref identifies the subproject axis. It could be <project-id>, ProjectRef(uri("file:..."), "id"), or ThisBuild that denotes the “entire build” scope.
• Config identifies the configuration axis using the capitalized Scala identifier.
• intask identifies the task axis.
• key identifies the key being scoped.

Zero can appear for each axis.

If you omit part of the scoped key, it will be inferred as follows:

• the current project will be used if you omit the project.
• a key-dependent configuration will be auto-detected if you omit the configuration or task.

For more details, see Interacting with the Configuration System.

Examples of scoped key notation in the sbt shell 

• fullClasspath specifies just a key, so the default scopes are used: current project, a key-dependent configuration, and Zero task scope.
• Test / fullClasspath specifies the configuration, so this is fullClasspath in the Test configuration, with defaults for the other two scope axes.
• root / fullClasspath specifies the project root, where the project is identified with the project id.
• root / Zero / fullClasspath specified the project root, and specifies Zero for the configuration, rather than the default configuration.
• doc / fullClasspath specifies the fullClasspath key scoped to the doc task, with the defaults for the project and configuration axes.
• ProjectRef(uri("file:/tmp/hello/"), "root") / Test / fullClasspath specifies a project ProjectRef(uri("file:/tmp/hello/"), "root"). Also specifies configuration Test, leaves the default task axis.
• ThisBuild / version sets the subproject axis to “entire build” where the build is ThisBuild, with the default configuration.
• Zero / fullClasspath sets the subproject axis to Zero, with the default configuration.
• root / Compile / doc / fullClasspath sets all three scope axes.

Inspecting scopes 

In sbt shell, you can use the inspect command to understand keys and their scopes. Try inspect Test/fullClasspath:

$ sbt
sbt:Hello> inspect Test / fullClasspath
[info] Task: scala.collection.Seq[sbt.internal.util.Attributed[java.io.File]]
[info] Description:
[info]  The exported classpath, consisting of build products and unmanaged and managed, internal and external dependencies.
[info] Provided by:
[info]  ProjectRef(uri("file:/tmp/hello/"), "root") / Test / fullClasspath
[info] Defined at:
[info]  (sbt.Classpaths.classpaths) Defaults.scala:1639
[info] Dependencies:
[info]  Test / dependencyClasspath
[info]  Test / exportedProducts
[info]  Test / fullClasspath / streams
[info] Reverse dependencies:
[info]  Test / testLoader
[info] Delegates:
[info]  Test / fullClasspath
[info]  Runtime / fullClasspath
[info]  Compile / fullClasspath
[info]  fullClasspath
[info]  ThisBuild / Test / fullClasspath
[info]  ThisBuild / Runtime / fullClasspath
[info]  ThisBuild / Compile / fullClasspath
[info]  ThisBuild / fullClasspath
[info]  Zero / Test / fullClasspath
[info]  Zero / Runtime / fullClasspath
[info]  Zero / Compile / fullClasspath
[info]  Global / fullClasspath
[info] Related:
[info]  Compile / fullClasspath
[info]  Runtime / fullClasspath

On the first line, you can see this is a task (as opposed to a setting, as explained in .sbt build definition). The value resulting from the task will have type scala.collection.Seq[sbt.Attributed[java.io.File]].

“Provided by” points you to the scoped key that defines the value, in this case ProjectRef(uri("file:/tmp/hello/"), "root") / Test / fullClasspath (which is the fullClasspath key scoped to the Test configuration and the ProjectRef(uri("file:/tmp/hello/"), "root") project).

“Dependencies” was discussed in detail in the previous page.

We’ll discuss “Delegates” later.

Try inspect fullClasspath (as opposed to the above example, inspect Test / fullClasspath) to get a sense of the difference. Because the configuration is omitted, it is autodetected as Compile. inspect Compile / fullClasspath should therefore look the same as inspect fullClasspath.

Try inspect ThisBuild / Zero / fullClasspath for another contrast. fullClasspath is not defined in the Zero configuration scope by default.

Again, for more details, see Interacting with the Configuration System.

When to specify a scope 

You need to specify the scope if the key in question is normally scoped. For example, the compile task, by default, is scoped to Compile and Test configurations, and does not exist outside of those scopes.

To change the value associated with the compile key, you need to write Compile / compile or Test / compile. Using plain compile would define a new compile task scoped to the current project, rather than overriding the standard compile tasks which are scoped to a configuration.

If you get an error like “Reference to undefined setting“, often you’ve failed to specify a scope, or you’ve specified the wrong scope. The key you’re using may be defined in some other scope. sbt will try to suggest what you meant as part of the error message; look for “Did you mean Compile / compile?”

One way to think of it is that a name is only part of a key. In reality, all keys consist of both a name, and a scope (where the scope has three axes). The entire expression Compile / packageBin / packageOptions is a key name, in other words. Simply packageOptions is also a key name, but a different one (for keys with no slashes, a scope is implicitly assumed: current project, Zero config, Zero task).

Build-level settings 

An advanced technique for factoring out common settings across subprojects is to define the settings scoped to ThisBuild.

If a key that is scoped to a particular subproject is not found, sbt will look for it in ThisBuild as a fallback. Using the mechanism, we can define a build-level default setting for frequently used keys such as version, scalaVersion, and organization.

ThisBuild / organization := "com.example",
ThisBuild / scalaVersion := "2.12.18",
ThisBuild / version      := "0.1.0-SNAPSHOT"

lazy val root = (project in file("."))
  .settings(
    name := "Hello",
    publish / skip := true
  )

lazy val core = (project in file("core"))
  .settings(
    // other settings
  )

lazy val util = (project in file("util"))
  .settings(
    // other settings
  )

For convenience, there is inThisBuild(...) function that will scope both the key and the body of the setting expression to ThisBuild. Putting setting expressions in there would be equivalent to prepending ThisBuild / where possible.

Due to the nature of scope delegation that we will cover later, build-level settings should be set only to a pure value or settings from either Global or ThisBuild scoping.

Scope delegation 

A scoped key may be undefined, if it has no value associated with it in its scope.

For each scope axis, sbt has a fallback search path made up of other scope values. Typically, if a key has no associated value in a more-specific scope, sbt will try to get a value from a more general scope, such as the ThisBuild scope.

This feature allows you to set a value once in a more general scope, allowing multiple more-specific scopes to inherit the value. We will discuss scope delegation in detail later.

Appending values 

Appending to previous values: += and ++= 

Assignment with := is the simplest transformation, but keys have other methods as well. If the T in SettingKey[T] is a sequence, i.e. the key’s value type is a sequence, you can append to the sequence rather than replacing it.

• += will append a single element to the sequence.
• ++= will concatenate another sequence.

For example, the key Compile / sourceDirectories has a Seq[File] as its value. By default this key’s value would include src/main/scala. If you wanted to also compile source code in a directory called source (since you just have to be nonstandard), you could add that directory:

Compile / sourceDirectories += new File("source")

Or, using the file() function from the sbt package for convenience:

Compile / sourceDirectories += file("source")

(file() just creates a new File.)

You could use ++= to add more than one directory at a time:

Compile / sourceDirectories ++= Seq(file("sources1"), file("sources2"))

Where Seq(a, b, c, ...) is standard Scala syntax to construct a sequence.

To replace the default source directories entirely, you use := of course:

Compile / sourceDirectories := Seq(file("sources1"), file("sources2"))

When settings are undefined 

Whenever a setting uses :=, +=, or ++= to create a dependency on itself or another key’s value, the value it depends on must exist. If it does not, sbt will complain. It might say “Reference to undefined setting“, for example. When this happens, be sure you’re using the key in the scope that defines it.

It’s possible to create cycles, which is an error; sbt will tell you if you do this.

Tasks based on other keys’ values 

You can compute values of some tasks or settings to define or append a value for another task. It’s done by using Def.task as an argument to :=, +=, or ++=.

As a first example, consider appending a source generator using the project base directory and compilation classpath.

Compile / sourceGenerators += Def.task {
  myGenerator(baseDirectory.value, (Compile / managedClasspath).value)
}

Appending with dependencies: += and ++= 

Other keys can be used when appending to an existing setting or task, just like they can for assigning with :=.

For example, say you have a coverage report named after the project, and you want to add it to the files removed by clean:

cleanFiles += file("coverage-report-" + name.value + ".txt")

Scope delegation (.value lookup) 

This page describes scope delegation. It assumes you’ve read and understood the previous pages, build definition and scopes.

Now that we’ve covered all the details of scoping, we can explain the .value lookup in detail. It’s ok to skip this section if this is your first time reading this page.

To summarize what we’ve learned so far:

• A scope is a tuple of components in three axes: the subproject axis, the configuration axis, and the task axis.
• There’s a special scope component Zero for any of the scope axes.
• There’s a special scope component ThisBuild for the subprojects axis only.
• Test extends Runtime, and Runtime extends Compile configuration.
• A key placed in build.sbt is scoped to ${current subproject} / Zero / Zero by default.
• A key can be scoped using / operator.

Now let’s suppose we have the following build definition:

lazy val foo = settingKey[Int]("")
lazy val bar = settingKey[Int]("")

lazy val projX = (project in file("x"))
  .settings(
    foo := {
      (Test / bar).value + 1
    },
    Compile / bar := 1
  )

Inside of foo’s setting body a dependency on the scoped key Test / bar is declared. However, despite Test / bar being undefined in projX, sbt is still able to resolve Test / bar to another scoped key, resulting in foo initialized as 2.

sbt has a well-defined fallback search path called scope delegation. This feature allows you to set a value once in a more general scope, allowing multiple more-specific scopes to inherit the value.

Scope delegation rules 

Here are the rules for scope delegation:

• Rule 1: Scope axes have the following precedence: the subproject axis, the configuration axis, and then the task axis.
• Rule 2: Given a scope, delegate scopes are searched by substituting the task axis in the following order: the given task scoping, and then Zero, which is non-task scoped version of the scope.
• Rule 3: Given a scope, delegate scopes are searched by substituting the configuration axis in the following order: the given configuration, its parents, their parents and so on, and then Zero (same as unscoped configuration axis).
• Rule 4: Given a scope, delegate scopes are searched by substituting the subproject axis in the following order: the given subproject, ThisBuild, and then Zero.
• Rule 5: A delegated scoped key and its dependent settings/tasks are evaluated without carrying the original context.

We will look at each rule in the rest of this page.

Rule 1: Scope axis precedence 

• Rule 1: Scope axes have the following precedence: the subproject axis, the configuration axis, and then the task axis.

In other words, given two scope candidates, if one has more specific value on the subproject axis, it will always win regardless of the configuration or the task scoping. Similarly, if subprojects are the same, one with more specific configuration value will always win regardless of the task scoping. We will see more rules to define more specific.

Rule 2: The task axis delegation 

• Rule 2: Given a scope, delegate scopes are searched by substituting the task axis in the following order: the given task scoping, and then Zero, which is non-task scoped version of the scope.

Here we have a concrete rule for how sbt will generate delegate scopes given a key. Remember, we are trying to show the search path given an arbitrary (xxx / yyy).value.

Exercise A: Given the following build definition:

lazy val projA = (project in file("a"))
  .settings(
    name := {
      "foo-" + (packageBin / scalaVersion).value
    },
    scalaVersion := "2.11.11"
  )

What is the value of projA / name?

1. "foo-2.11.11"
2. "foo-2.12.18"
3. something else?

The answer is "foo-2.11.11". Inside of .settings(...), scalaVersion is automatically scoped to projA / Zero / Zero, so packageBin / scalaVersion becomes projA / Zero / packageBin / scalaVersion. That particular scoped key is undefined. By using Rule 2, sbt will substitute the task axis to Zero as projA / Zero / Zero (or projA / scalaVersion). That scoped key is defined to be "2.11.11".

Rule 3: The configuration axis search path 

• Rule 3: Given a scope, delegate scopes are searched by substituting the configuration axis in the following order: the given configuration, its parents, their parents and so on, and then Zero (same as unscoped configuration axis).

The example for that is projX that we saw earlier:

lazy val foo = settingKey[Int]("")
lazy val bar = settingKey[Int]("")

lazy val projX = (project in file("x"))
  .settings(
    foo := {
      (Test / bar).value + 1
    },
    Compile / bar := 1
  )

If we write out the full scope again, it’s projX / Test / Zero. Also recall that Test extends Runtime, and Runtime extends Compile.

Test / bar is undefined, but due to Rule 3 sbt will look for bar scoped in projX / Test / Zero, projX / Runtime / Zero, and then projX / Compile / Zero. The last one is found, which is Compile / bar.

Rule 4: The subproject axis search path 

• Rule 4: Given a scope, delegate scopes are searched by substituting the subproject axis in the following order: the given subproject, ThisBuild, and then Zero.

Exercise B: Given the following build definition:

ThisBuild / organization := "com.example"

lazy val projB = (project in file("b"))
  .settings(
    name := "abc-" + organization.value,
    organization := "org.tempuri"
  )

What is the value of projB / name?

1. "abc-com.example"
2. "abc-org.tempuri"
3. something else?

The answer is abc-org.tempuri. So based on Rule 4, the first search path is organization scoped to projB / Zero / Zero, which is defined in projB as "org.tempuri". This has higher precedence than the build-level setting ThisBuild / organization.

Scope axis precedence, again 

Exercise C: Given the following build definition:

ThisBuild / packageBin / scalaVersion := "2.12.2"

lazy val projC = (project in file("c"))
  .settings(
    name := {
      "foo-" + (packageBin / scalaVersion).value
    },
    scalaVersion := "2.11.11"
  )

What is value of projC / name?

1. "foo-2.12.2"
2. "foo-2.11.11"
3. something else?

The answer is foo-2.11.11. scalaVersion scoped to projC / Zero / packageBin is undefined. Rule 2 finds projC / Zero / Zero. Rule 4 finds ThisBuild / Zero / packageBin. In this case Rule 1 dictates that more specific value on the subproject axis wins, which is projC / Zero / Zero that is defined to "2.11.11".

Exercise D: Given the following build definition:

ThisBuild / scalacOptions += "-Ywarn-unused-import"

lazy val projD = (project in file("d"))
  .settings(
    test := {
      println((Compile / console / scalacOptions).value)
    },
    console / scalacOptions -= "-Ywarn-unused-import",
    Compile / scalacOptions := scalacOptions.value // added by sbt
  )

What would you see if you ran projD/test?

1. List()
2. List(-Ywarn-unused-import)
3. something else?

The answer is List(-Ywarn-unused-import). Rule 2 finds projD / Compile / Zero, Rule 3 finds projD / Zero / console, and Rule 4 finds ThisBuild / Zero / Zero. Rule 1 selects projD / Compile / Zero because it has the subproject axis projD, and the configuration axis has higher precedence over the task axis.

Next, Compile / scalacOptions refers to scalacOptions.value, we next need to find a delegate for projD / Zero / Zero. Rule 4 finds ThisBuild / Zero / Zero and thus it resolves to List(-Ywarn-unused-import).

Inspect command lists the delegates 

You might want to look up quickly what is going on. This is where inspect can be used.

sbt:projd> inspect projD / Compile / console / scalacOptions
[info] Task: scala.collection.Seq[java.lang.String]
[info] Description:
[info]  Options for the Scala compiler.
[info] Provided by:
[info]  ProjectRef(uri("file:/tmp/projd/"), "projD") / Compile / scalacOptions
[info] Defined at:
[info]  /tmp/projd/build.sbt:9
[info] Reverse dependencies:
[info]  projD / test
[info]  projD / Compile / console
[info] Delegates:
[info]  projD / Compile / console / scalacOptions
[info]  projD / Compile / scalacOptions
[info]  projD / console / scalacOptions
[info]  projD / scalacOptions
[info]  ThisBuild / Compile / console / scalacOptions
[info]  ThisBuild / Compile / scalacOptions
[info]  ThisBuild / console / scalacOptions
[info]  ThisBuild / scalacOptions
[info]  Zero / Compile / console / scalacOptions
[info]  Zero / Compile / scalacOptions
[info]  Zero / console / scalacOptions
[info]  Global / scalacOptions

Note how “Provided by” shows that projD / Compile / console / scalacOptions is provided by projD / Compile / scalacOptions. Also under “Delegates”, all of the possible delegate candidates listed in the order of precedence!

• All the scopes with projD scoping on the subproject axis are listed first, then ThisBuild, and Zero.
• Within a subproject, scopes with Compile scoping on the configuration axis are listed first, then falls back to Zero.
• Finally, the task axis scoping lists the given task scoping console / and the one without.

.value lookup vs dynamic dispatch 

• Rule 5: A delegated scoped key and its dependent settings/tasks are evaluated without carrying the original context.

Note that scope delegation feels similar to class inheritance in an object-oriented language, but there’s a difference. In an OO language like Scala if there’s a method named drawShape on a trait Shape, its subclasses can override the behavior even when drawShape is used by other methods in the Shape trait, which is called dynamic dispatch.

In sbt, however, scope delegation can delegate a scope to a more general scope, like a project-level setting to a build-level settings, but that build-level setting cannot refer to the project-level setting.

Exercise E: Given the following build definition:

lazy val root = (project in file("."))
  .settings(
    inThisBuild(List(
      organization := "com.example",
      scalaVersion := "2.12.2",
      version      := scalaVersion.value + "_0.1.0"
    )),
    name := "Hello"
  )

lazy val projE = (project in file("e"))
  .settings(
    scalaVersion := "2.11.11"
  )

What will projE / version return?

1. "2.12.2_0.1.0"
2. "2.11.11_0.1.0"
3. something else?

The answer is 2.12.2_0.1.0. projE / version delegates to ThisBuild / version, which depends on ThisBuild / scalaVersion. Because of this reason, build level setting should be limited mostly to simple value assignments.

Exercise F: Given the following build definition:

ThisBuild / scalacOptions += "-D0"
scalacOptions += "-D1"

lazy val projF = (project in file("f"))
  .settings(
    compile / scalacOptions += "-D2",
    Compile / scalacOptions += "-D3",
    Compile / compile / scalacOptions += "-D4",
    test := {
      println("bippy" + (Compile / compile / scalacOptions).value.mkString)
    }
  )

What will projF / test show?

1. "bippy-D4"
2. "bippy-D2-D4"
3. "bippy-D0-D3-D4"
4. something else?

The answer is "bippy-D0-D3-D4". This is a variation of an exercise originally created by Paul Phillips.

It’s a great demonstration of all the rules because someKey += "x" expands to

someKey := {
  val old = someKey.value
  old :+ "x"
}

Retrieving the old value would cause delegation, and due to Rule 5, it will go to another scoped key. Let’s get rid of += first, and annotate the delegates for old values:

ThisBuild / scalacOptions := {
  // Global / scalacOptions <- Rule 4
  val old = (ThisBuild / scalacOptions).value
  old :+ "-D0"
}

scalacOptions := {
  // ThisBuild / scalacOptions <- Rule 4
  val old = scalacOptions.value
  old :+ "-D1"
}

lazy val projF = (project in file("f"))
  .settings(
    compile / scalacOptions := {
      // ThisBuild / scalacOptions <- Rules 2 and 4
      val old = (compile / scalacOptions).value
      old :+ "-D2"
    },
    Compile / scalacOptions := {
      // ThisBuild / scalacOptions <- Rules 3 and 4
      val old = (Compile / scalacOptions).value
      old :+ "-D3"
    },
    Compile / compile / scalacOptions := {
      // projF / Compile / scalacOptions <- Rules 1 and 2
      val old = (Compile / compile / scalacOptions).value
      old :+ "-D4"
    },
    test := {
      println("bippy" + (Compile / compile / scalacOptions).value.mkString)
    }
  )

This becomes:

ThisBuild / scalacOptions := {
  Nil :+ "-D0"
}

scalacOptions := {
  List("-D0") :+ "-D1"
}

lazy val projF = (project in file("f"))
  .settings(
    compile / scalacOptions := List("-D0") :+ "-D2",
    Compile / scalacOptions := List("-D0") :+ "-D3",
    Compile / compile / scalacOptions := List("-D0", "-D3") :+ "-D4",
    test := {
      println("bippy" + (Compile / compile / scalacOptions).value.mkString)
    }
  )

Library dependencies 

This page assumes you’ve already read the earlier Getting Started pages, in particular build definition, scopes, and task graph.

Library dependencies can be added in two ways:

• unmanaged dependencies are jars dropped into the lib directory
• managed dependencies are configured in the build definition and downloaded automatically from repositories

Unmanaged dependencies 

Most people use managed dependencies instead of unmanaged. But unmanaged can be simpler when starting out.

Unmanaged dependencies work like this: add jars to lib and they will be placed on the project classpath. Not much else to it!

You can place test jars such as ScalaCheck, Specs2, and ScalaTest in lib as well.

Dependencies in lib go on all the classpaths (for compile, test, run, and console). If you wanted to change the classpath for just one of those, you would adjust Compile / dependencyClasspath or Runtime / dependencyClasspath for example.

There’s nothing to add to build.sbt to use unmanaged dependencies, though you could change the unmanagedBase key if you’d like to use a different directory rather than lib.

To use custom_lib instead of lib:

unmanagedBase := baseDirectory.value / "custom_lib"

baseDirectory is the project’s root directory, so here you’re changing unmanagedBase depending on baseDirectory using the special value method as explained in task graph.

There’s also an unmanagedJars task which lists the jars from the unmanagedBase directory. If you wanted to use multiple directories or do something else complex, you might need to replace the whole unmanagedJars task with one that does something else, e.g. empty the list for Compile configuration regardless of the files in lib directory:

Compile / unmanagedJars := Seq.empty[sbt.Attributed[java.io.File]]

Managed Dependencies 

sbt uses Coursier to implement managed dependencies, so if you’re familiar with Coursier, Apache Ivy or Maven, you won’t have much trouble.

The libraryDependencies key 

Most of the time, you can simply list your dependencies in the setting libraryDependencies. It’s also possible to write a Maven POM file or Ivy configuration file to externally configure your dependencies, and have sbt use those external configuration files. You can learn more about that here.

Declaring a dependency looks like this, where groupId, artifactId, and revision are strings:

libraryDependencies += groupID % artifactID % revision

or like this, where configuration can be a string or a Configuration value (such as Test):

libraryDependencies += groupID % artifactID % revision % configuration

libraryDependencies is declared in Keys like this:

val libraryDependencies = settingKey[Seq[ModuleID]]("Declares managed dependencies.")

The % methods create ModuleID objects from strings, then you add those ModuleID to libraryDependencies.

Of course, sbt (via Coursier) has to know where to download the module. If your module is in one of the default repositories sbt comes with, this will just work. For example, Apache Derby is in the standard Maven2 repository:

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

If you type that in build.sbt and then update, sbt should download Derby to the Coursier cache. (By the way, update is a dependency of compile so there’s no need to manually type update most of the time.)

Of course, you can also use ++= to add a list of dependencies all at once:

libraryDependencies ++= Seq(
  groupID % artifactID % revision,
  groupID % otherID % otherRevision
)

In rare cases you might find reasons to use := with libraryDependencies as well.

Getting the right Scala version with %% 

If you use organization %% moduleName % version rather than organization % moduleName % version (the difference is the double %% after the organization), sbt will add your project’s binary Scala version to the artifact name. This is just a shortcut. You could write this without the %%:

libraryDependencies += "org.scala-stm" % "scala-stm_2.13" % "0.9.1"

Assuming the scalaVersion for your build is 2.13.12, the following is identical (note the double %% after "org.scala-stm"):

libraryDependencies += "org.scala-stm" %% "scala-stm" % "0.9.1"

The idea is that many dependencies are compiled for multiple Scala versions, and you’d like to get the one that matches your project to ensure binary compatibility.

See Cross Building for some more detail on this.

Ivy revisions 

The version in organization % moduleName % version does not have to be a single fixed version. Ivy can select the latest revision of a module according to constraints you specify. Instead of a fixed revision like "1.6.1", you specify "latest.integration", "2.9.+", or "[1.0,)". See the Ivy revisions documentation for details.

Occasionally a Maven “version range” is used to specify a dependency (transitive or otherwise), such as [1.3.0,). If a specific version of the dependency is declared in the build, and it satisfies the range, then sbt will use the specified version. Otherwise, Coursier could go out to the Internet to find the latest version. This would result to a surprising behavior where the effective version keeps changing over time, even though there’s a specified version of the library that satisfies the range condition.

Maven version ranges will be replaced with its lower bound if the build so that when a satisfactory version is found in the dependency graph it will be used. You can disable this behavior using the JVM flag -Dsbt.modversionrange=false.

Resolvers 

Not all packages live on the same server; sbt uses the standard Maven2 repository by default. If your dependency isn’t on one of the default repositories, you’ll have to add a resolver to help Ivy find it.

To add an additional repository, use

resolvers += name at location

with the special at between two strings.

For example:

resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"

The resolvers key is defined in Keys like this:

val resolvers = settingKey[Seq[Resolver]]("The user-defined additional resolvers for automatically managed dependencies.")

The at method creates a Resolver object from two strings.

sbt can search your local Maven repository if you add it as a repository:

resolvers += "Local Maven Repository" at "file://"+Path.userHome.absolutePath+"/.m2/repository"

or, for convenience:

resolvers += Resolver.mavenLocal

See Resolvers for details on defining other types of repositories.

Overriding default resolvers 

resolvers does not contain the default resolvers; only additional ones added by your build definition.

sbt combines resolvers with some default repositories to form externalResolvers.

Therefore, to change or remove the default resolvers, you would need to override externalResolvers instead of resolvers.

Per-configuration dependencies 

Often a dependency is used by your test code (in src/test/scala, which is compiled by the Test configuration) but not your main code.

If you want a dependency to show up in the classpath only for the Test configuration and not the Compile configuration, add % "test" like this:

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

You may also use the type-safe version of Test configuration as follows:

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

Now, if you type show Compile/dependencyClasspath at the sbt interactive prompt, you should not see the derby jar. But if you type show Test/dependencyClasspath, you should see the derby jar in the list.

Typically, test-related dependencies such as ScalaCheck, Specs2, and ScalaTest would be defined with % "test".

There are more details and tips-and-tricks related to library dependencies on this page.

Using plugins 

Please read the earlier pages in the Getting Started Guide first, in particular you need to understand build.sbt, task graph, library dependencies, before reading this page.

What is a plugin? 

A plugin extends the build definition, most commonly by adding new settings. The new settings could be new tasks. For example, a plugin could add a codeCoverage task which would generate a test coverage report.

Declaring a plugin 

If your project is in directory hello, and you’re adding sbt-site plugin to the build definition, create hello/project/site.sbt and declare the plugin dependency by passing the plugin’s Ivy module ID to addSbtPlugin:

addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "0.7.0")

If you’re adding sbt-assembly, create hello/project/assembly.sbt with the following:

addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.11.2")

Not every plugin is located on one of the default repositories and a plugin’s documentation may instruct you to also add the repository where it can be found:

resolvers ++= Resolver.sonatypeOssRepos("public")

Plugins usually provide settings that get added to a project to enable the plugin’s functionality. This is described in the next section.

Enabling and disabling auto plugins 

A plugin can declare that its settings be automatically added to the build definition, in which case you don’t have to do anything to add them.

As of sbt 0.13.5, there is a new auto plugins feature that enables plugins to automatically, and safely, ensure their settings and dependencies are on a project. Many auto plugins should have their default settings automatically, however some may require explicit enablement.

If you’re using an auto plugin that requires explicit enablement, then you have to add the following to your build.sbt:

lazy val util = (project in file("util"))
  .enablePlugins(FooPlugin, BarPlugin)
  .settings(
    name := "hello-util"
  )

The enablePlugins method allows projects to explicitly define the auto plugins they wish to consume.

Projects can also exclude plugins using the disablePlugins method. For example, if we wish to remove the IvyPlugin settings from util, we modify our build.sbt as follows:

lazy val util = (project in file("util"))
  .enablePlugins(FooPlugin, BarPlugin)
  .disablePlugins(plugins.IvyPlugin)
  .settings(
    name := "hello-util"
  )

Auto plugins should document whether they need to be explicitly enabled. If you’re curious which auto plugins are enabled for a given project, just run the plugins command on the sbt console.

For example:

> plugins
In file:/home/jsuereth/projects/sbt/test-ivy-issues/
        sbt.plugins.IvyPlugin: enabled in scala-sbt-org
        sbt.plugins.JvmPlugin: enabled in scala-sbt-org
        sbt.plugins.CorePlugin: enabled in scala-sbt-org
        sbt.plugins.JUnitXmlReportPlugin: enabled in scala-sbt-org

Here, the plugins output is showing that the sbt default plugins are all enabled. sbt’s default settings are provided via three plugins:

1. CorePlugin: Provides the core parallelism controls for tasks.
2. IvyPlugin: Provides the mechanisms to publish/resolve modules.
3. JvmPlugin: Provides the mechanisms to compile/test/run/package Java/Scala projects.

In addition, JUnitXmlReportPlugin provides an experimental support for generating junit-xml.

Older non-auto plugins often require settings to be added explicitly, so that multi-project build could have different types of projects. The plugin documentation will indicate how to configure it, but typically for older plugins this involves adding the base settings for the plugin and customizing as necessary.

For example, for the sbt-site plugin, create site.sbt with the following content

site.settings

to enable it for that project.

If the build defines multiple projects, instead add it directly to the project:

// don't use the site plugin for the `util` project
lazy val util = (project in file("util"))

// enable the site plugin for the `core` project
lazy val core = (project in file("core"))
  .settings(site.settings)

Global plugins 

Plugins can be installed for all your projects at once by declaring them in $HOME/.sbt/1.0/plugins/. $HOME/.sbt/1.0/plugins/ is an sbt project whose classpath is exported to all sbt build definition projects. Roughly speaking, any .sbt or .scala files in $HOME/.sbt/1.0/plugins/ behave as if they were in the project/ directory for all projects.

You can create $HOME/.sbt/1.0/plugins/build.sbt and put addSbtPlugin() expressions in there to add plugins to all your projects at once. Because doing so would increase the dependency on the machine environment, this feature should be used sparingly. See Best Practices.

Available Plugins 

There’s a list of available plugins.

Some especially popular plugins are:

• those for IDEs (to import an sbt project into your IDE)
• those supporting web frameworks, such as xsbt-web-plugin.

For more details, including ways of developing plugins, see Plugins. For best practices, see Plugins-Best-Practices.

Custom settings and tasks 

This page gets you started creating your own settings and tasks.

To understand this page, be sure you’ve read earlier pages in the Getting Started Guide, especially build.sbt and task graph.

Defining a key 

Keys is packed with examples illustrating how to define keys. Most of the keys are implemented in Defaults.

Keys have one of three types. SettingKey and TaskKey are described in .sbt build definition. Read about InputKey on the Input Tasks page.

Some examples from Keys:

val scalaVersion = settingKey[String]("The version of Scala used for building.")
val clean = taskKey[Unit]("Deletes files produced by the build, such as generated sources, compiled classes, and task caches.")

The key constructors have two string parameters: the name of the key ("scalaVersion") and a documentation string ("The version of scala used for building.").

Remember from .sbt build definition that the type parameter T in SettingKey[T] indicates the type of value a setting has. T in TaskKey[T] indicates the type of the task’s result. Also remember from .sbt build definition that a setting has a fixed value until project reload, while a task is re-computed for every “task execution” (every time someone types a command at the sbt interactive prompt or in batch mode).

Keys may be defined in an .sbt file, a .scala file, or in an auto plugin. Any vals found under autoImport object of an enabled auto plugin will be imported automatically into your .sbt files.

Implementing a task 

Once you’ve defined a key for your task, you’ll need to complete it with a task definition. You could be defining your own task, or you could be planning to redefine an existing task. Either way looks the same; use := to associate some code with the task key:

val sampleStringTask = taskKey[String]("A sample string task.")
val sampleIntTask = taskKey[Int]("A sample int task.")

ThisBuild / organization := "com.example"
ThisBuild / version      := "0.1.0-SNAPSHOT"
ThisBuild / scalaVersion := "2.12.18"

lazy val library = (project in file("library"))
  .settings(
    sampleStringTask := System.getProperty("user.home"),
    sampleIntTask := {
      val sum = 1 + 2
      println("sum: " + sum)
      sum
    }
  )

If the task has dependencies, you’d reference their value using value, as discussed in task graph.

The hardest part about implementing tasks is often not sbt-specific; tasks are just Scala code. The hard part could be writing the “body” of your task that does whatever you’re trying to do. For example, maybe you’re trying to format HTML in which case you might want to use an HTML library (you would add a library dependency to your build definition and write code based on the HTML library, perhaps).

sbt has some utility libraries and convenience functions, in particular you can often use the convenient APIs in IO to manipulate files and directories.

Execution semantics of tasks 

When depending on other tasks from a custom task using value, an important detail to note is the execution semantics of the tasks. By execution semantics, we mean exactly when these tasks are evaluated.

If we take sampleIntTask for instance, each line in the body of the task should be strictly evaluated one after the other. That is sequential semantics:

sampleIntTask := {
  val sum = 1 + 2        // first
  println("sum: " + sum) // second
  sum                    // third
}

In reality JVM may inline the sum to 3, but the observable effect of the task will remain identical as if each line were executed one after the other.

Now suppose we define two more custom tasks startServer and stopServer, and modify sampleIntTask as follows:

val startServer = taskKey[Unit]("start server")
val stopServer = taskKey[Unit]("stop server")
val sampleIntTask = taskKey[Int]("A sample int task.")
val sampleStringTask = taskKey[String]("A sample string task.")

ThisBuild / organization := "com.example"
ThisBuild / version      := "0.1.0-SNAPSHOT"
ThisBuild / scalaVersion := "2.12.18"

lazy val library = (project in file("library"))
  .settings(
    startServer := {
      println("starting...")
      Thread.sleep(500)
    },
    stopServer := {
      println("stopping...")
      Thread.sleep(500)
    },
    sampleIntTask := {
      startServer.value
      val sum = 1 + 2
      println("sum: " + sum)
      stopServer.value // THIS WON'T WORK
      sum
    },
    sampleStringTask := {
      startServer.value
      val s = sampleIntTask.value.toString
      println("s: " + s)
      s
    }
  )

Running sampleIntTask from sbt interactive prompt results to the following:

> sampleIntTask
stopping...
starting...
sum: 3
[success] Total time: 1 s, completed Dec 22, 2014 5:00:00 PM

To review what happened, let’s look at a graphical notation of sampleIntTask:

Unlike plain Scala method calls, invoking value method on tasks will not be evaluated strictly. Instead, they simply act as placeholders to denote that sampleIntTask depends on startServer and stopServer tasks. When sampleIntTask is invoked by you, sbt’s tasks engine will:

• evaluate the task dependencies before evaluating sampleIntTask (partial ordering)
• try to evaluate task dependencies in parallel if they are independent (parallelization)
• each task dependency will be evaluated once and only once per command execution (deduplication)

Deduplication of task dependencies 

To demonstrate the last point, we can run sampleStringTask from sbt interactive prompt.

> sampleStringTask
stopping...
starting...
sum: 3
s: 3
[success] Total time: 1 s, completed Dec 22, 2014 5:30:00 PM

Because sampleStringTask depends on both startServer and sampleIntTask task, and sampleIntTask also depends on startServer task, it appears twice as task dependency. If this was a plain Scala method call it would be evaluated twice, but since value is just denoting a task dependency, it will be evaluated once. The following is a graphical notation of sampleStringTask’s evaluation:

If we did not deduplicate the task dependencies, we will end up compiling test source code many times when test task is invoked since Test / compile appears many times as a task dependency of Test / test.

Cleanup task 

How should one implement stopServer task? The notion of cleanup task does not fit into the execution model of tasks because tasks are about tracking dependencies. The last operation should become the task that depends on other intermediate tasks. For instance stopServer should depend on sampleStringTask, at which point stopServer should be the sampleStringTask.

lazy val library = (project in file("library"))
  .settings(
    startServer := {
      println("starting...")
      Thread.sleep(500)
    },
    sampleIntTask := {
      startServer.value
      val sum = 1 + 2
      println("sum: " + sum)
      sum
    },
    sampleStringTask := {
      startServer.value
      val s = sampleIntTask.value.toString
      println("s: " + s)
      s
    },
    sampleStringTask := {
      val old = sampleStringTask.value
      println("stopping...")
      Thread.sleep(500)
      old
    }
  )

To demonstrate that it works, run sampleStringTask from the interactive prompt:

> sampleStringTask
starting...
sum: 3
s: 3
stopping...
[success] Total time: 1 s, completed Dec 22, 2014 6:00:00 PM

Use plain Scala 

Another way of making sure that something happens after some other thing is to use Scala. Implement a simple function in project/ServerUtil.scala for example, and you can write:

sampleIntTask := {
  ServerUtil.startServer
  try {
    val sum = 1 + 2
    println("sum: " + sum)
  } finally {
    ServerUtil.stopServer
  }
  sum
}

Since plain method calls follow sequential semantics, everything happens in order. There’s no deduplication, so you have to be careful about that.

Turn them into plugins 

If you find you have a lot of custom code, consider moving it to a plugin for re-use across multiple builds.

It’s very easy to create a plugin, as teased earlier and discussed at more length here.

This page has been a quick taste; there’s much much more about custom tasks on the Tasks page.

Organizing the build 

This page discusses the organization of the build structure.

Please read the earlier pages in the Getting Started Guide first, in particular you need to understand build.sbt, task graph, Library dependencies, and Multi-project builds before reading this page.

sbt is recursive 

build.sbt conceals how sbt really works. sbt builds are defined with Scala code. That code, itself, has to be built. What better way than with sbt?

The project directory is another build inside your build, which knows how to build your build. To distinguish the builds, we sometimes use the term proper build to refer to your build, and meta-build to refer to the build in project. The projects inside the metabuild can do anything any other project can do. Your build definition is an sbt project.

And the turtles go all the way down. If you like, you can tweak the build definition of the build definition project, by creating a project/project/ directory.

Here’s an illustration.

hello/                     # your build's root project's base directory

    Hello.scala            # a source file in your build's root project
                           #   (could be in src/main/scala too)

    build.sbt              # build.sbt is part of the source code for
                           #   meta-build's root project inside project/;
                           #   the build definition for your build

    project/               # base directory of meta-build's root project

        Dependencies.scala # a source file in the meta-build's root project,
                           #   that is, a source file in the build definition
                           #   the build definition for your build

        assembly.sbt       # this is part of the source code for
                           #   meta-meta-build's root project in project/project;
                           #   build definition's build definition

        project/           # base directory of meta-meta-build's root project;
                           #   the build definition project for the build definition

            MetaDeps.scala # source file in the root project of
                           #   meta-meta-build in project/project/

Don’t worry! Most of the time you are not going to need all that. But understanding the principle can be helpful.

By the way: any time files ending in .scala or .sbt are used, naming them build.sbt and Dependencies.scala are conventions only. This also means that multiple files are allowed.

Tracking dependencies in one place 

One way of using the fact that .scala files under project becomes part of the build definition is to create project/Dependencies.scala to track dependencies in one place.

import sbt._

object Dependencies {
  // Versions
  lazy val akkaVersion = "2.6.21"

  // Libraries
  val akkaActor = "com.typesafe.akka" %% "akka-actor" % akkaVersion
  val akkaCluster = "com.typesafe.akka" %% "akka-cluster" % akkaVersion
  val specs2core = "org.specs2" %% "specs2-core" % "4.20.0"

  // Projects
  val backendDeps =
    Seq(akkaActor, specs2core % Test)
}

The Dependencies object will be available in build.sbt. To make it easier to use the vals defined in it, import Dependencies._ in your build.sbt file.

import Dependencies._

ThisBuild / organization := "com.example"
ThisBuild / version      := "0.1.0-SNAPSHOT"
ThisBuild / scalaVersion := "2.12.18"

lazy val backend = (project in file("backend"))
  .settings(
    name := "backend",
    libraryDependencies ++= backendDeps
  )

This technique is useful when you have a multi-project build that’s getting large, and you want to ensure that subprojects have consistent dependencies.

When to use .scala files 

In .scala files, you can write any Scala code, including top-level classes and objects.

The recommended approach is to define most settings in a multi-project build.sbt file, and using project/*.scala files for task implementations or to share values, such as keys. The use of .scala files also depends on how comfortable you or your team are with Scala.

Defining auto plugins 

For more advanced users, another way of organizing your build is to define one-off auto plugins in project/*.scala. By defining triggered plugins, auto plugins can be used as a convenient way to inject custom tasks and commands across all subprojects.

Getting Started summary 

This page wraps up the Getting Started Guide.

To use sbt, there are a small number of concepts you must understand. These have some learning curve, but on the positive side, there isn’t much to sbt except these concepts. sbt uses a small core of powerful concepts to do everything it does.

If you’ve read the whole Getting Started series, now you know what you need to know.

sbt: The Core Concepts 

• the basics of Scala. It’s undeniably helpful to be familiar with Scala syntax. Programming in Scala written by the creator of Scala is a great introduction.
• .sbt build definition
• your build definition is a big DAG of tasks and their dependencies.
• to create a Setting, call one of a few methods on a key: :=, +=, or ++=.
• each setting has a value of a particular type, determined by the key.
• tasks are special settings where the computation to produce the key’s value will be re-run each time you kick off a task. Non-tasks compute the value once, when first loading the build definition.
• Scopes
• each key may have multiple values, in distinct scopes.
• scoping may use three axes: configuration, project, and task.
• scoping allows you to have different behaviors per-project, per-task, or per-configuration.
• a configuration is a kind of build, such as the main one (Compile) or the test one (Test).
• the per-project axis also supports “entire build” scope.
• scopes fall back to or delegate to more general scopes.
• put most of your configuration in build.sbt, but use .scala build definition files for defining classes and larger task implementations.
• the build definition is an sbt project in its own right, rooted in the project directory.
• Plugins are extensions to the build definition
• add plugins with the addSbtPlugin method in project/plugins.sbt (NOT build.sbt in the project’s base directory).

If any of this leaves you wondering rather than nodding, please ask for help, go back and re-read, or try some experiments in sbt’s interactive mode.

Good luck!

Advanced Notes 

Since sbt is open source, don’t forget you can check out the source code too!

Frequently Asked Questions 

Project Information 

What does the name “sbt” stand for, and why shouldn’t it be written “SBT”? 

TL;DR the name sbt doesn’t stand for anything, it’s just “sbt”, and it should be written that way.

When Mark Harrah (@harrah) first created the project he called it “Simple Build Tool”, but in his first public announcement of it he already referred to it as just “sbt”. Over time some have re-defined sbt to stand for “Scala Build Tool”, but we believe that isn’t accurate either given it can be used to build Java-only projects.

Nowadays we just call sbt “sbt”, and to reinforce that the name is no longer an initialism we always write it in all lowercase letters. However, we are cool with 酢豚 (subuta) as a nickname.

How do I get help? 

• See How can I get help?

How do I report a bug? 

• See Get Involved

How can I help? 

• See Get Involved

Usage 

My last command didn’t work but I can’t see an explanation. Why? 

sbt 1.9.8 by default suppresses most stack traces and debugging information. It has the nice side effect of giving you less noise on screen, but as a newcomer it can leave you lost for explanation. To see the previous output of a command at a higher verbosity, type last <task> where <task> is the task that failed or that you want to view detailed output for. For example, if you find that your update fails to load all the dependencies as you expect you can enter:

> last update

and it will display the full output from the last run of the update command.

How do I disable ansi codes in the output? 

Sometimes sbt doesn’t detect that ansi codes aren’t supported and you get output that looks like:

[0m[ [0minfo [0m]  [0mSet current project to root

or ansi codes are supported but you want to disable colored output. To completely disable ansi codes, pass -no-colors option:

$ sbt -no-colors

How can I start a Scala interpreter (REPL) with sbt project configuration (dependencies, etc.)? 

In sbt’s shell run console.

Build definitions 

What are the :=, +=, and ++= methods? 

These are methods on keys used to construct a Setting or a Task. The Getting Started Guide covers all these methods, see .sbt build definition, task graph, and appending values for example.

What is the % method? 

It’s used to create a ModuleID from strings, when specifying managed dependencies. Read the Getting Started Guide about library dependencies.

What does ThisBuild / scalaVersion mean? 

ThisBuild acts as a special subproject name that you can use to define default value for the build. When you define one or more subprojects, and when the subproject does not define scalaVersion key, it will look for ThisBuild / scalaVersion.

See build-wide settings.

What is ModuleID, Project, …? 

To figure out an unknown type or method, have a look at the Getting Started Guide if you have not. Also try the index of commonly used methods, values, and types, and the API Documentation.

How do I add files to a jar package? 

The files included in an artifact are configured by default by a task mappings that is scoped by the relevant package task. The mappings task returns a sequence Seq[(File,String)] of mappings from the file to include to the path within the jar. See mapping files for details on creating these mappings.

For example, to add generated sources to the packaged source artifact:

Compile / packageSrc / mappings ++= {
  import Path.{flat, relativeTo}
  val base = (Compile / sourceManaged).value
  val srcs = (Compile / managedSources).value
  srcs pair (relativeTo(base) | flat)
}

This takes sources from the managedSources task and relativizes them against the managedSource base directory, falling back to a flattened mapping. If a source generation task doesn’t write the sources to the managedSource directory, the mapping function would have to be adjusted to try relativizing against additional directories or something more appropriate for the generator.

How can I generate source code or resources? 

See Generating Files.

How can a task avoid redoing work if the input files are unchanged? 

See Caching.

Extending sbt 

How can I add a new dependency configuration? 

See How to define a custom dependency configuration.

How do I add a test configuration? 

See the Additional test configurations section of Testing.

How can I create a custom run task, in addition to run? 

This answer is extracted from a mailing list discussion.

Read the Getting Started Guide up to custom settings for background.

A basic run task is created by:

lazy val myRunTask = taskKey[Unit]("A custom run task.")

// this can go either in a `build.sbt` or the settings member
//   of a Project in a full configuration
fullRunTask(myRunTask, Test, "foo.Foo", "arg1", "arg2")

If you want to be able to supply arguments on the command line, replace TaskKey with InputKey and fullRunTask with fullRunInputTask. The Test part can be replaced with another configuration, such as Compile, to use that configuration’s classpath.

This run task can be configured individually by specifying the task key in the scope. For example:

myRunTask / fork := true

myRunTask / javaOptions += "-Xmx6144m"

How should I express a dependency on an outside tool such as proguard? 

Tool dependencies are used to implement a task and are not needed by project source code. These dependencies can be declared in their own configuration and classpaths. These are the steps:

1. Define a new configuration.
2. Declare the tool dependencies in that configuration.
3. Define a classpath that pulls the dependencies from the Update Report produced by update.
4. Use the classpath to implement the task.

As an example, consider a proguard task. This task needs the ProGuard jars in order to run the tool. First, define and add the new configuration:

lazy val ProguardConfig = config("proguard").hide

ivyConfigurations += ProguardConfig

Then,

// Add proguard as a dependency in the custom configuration.
//  This keeps it separate from project dependencies.
libraryDependencies +=
   "net.sf.proguard" % "proguard" % "4.4" % ProguardConfig.name

// Extract the dependencies from the UpdateReport.
ProguardConfig / managedClasspath := {
    // these are the types of artifacts to include
    val artifactTypes: Set[String] = (ProguardConfig / classpathTypes).value
    Classpaths.managedJars(proguardConfig, artifactTypes, update.value)
}

// Use the dependencies in a task, typically by putting them
//  in a ClassLoader and reflectively calling an appropriate
//  method.
proguard := {
    val cp: Seq[File] = (ProguardConfig / managedClasspath).value
  // ... do something with , which includes proguard ...
}

Defining the intermediate classpath is optional, but it can be useful for debugging or if it needs to be used by multiple tasks. It is also possible to specify artifact types inline. This alternative proguard task would look like:

proguard := {
   val artifactTypes = Set("jar")
    val cp =
      Classpaths.managedJars(proguardConfig, artifactTypes, update.value)
  // ... do something with , which includes proguard ...
}

How would I change sbt’s classpath dynamically? 

It is possible to register additional jars that will be placed on sbt’s classpath. Through State, it is possible to obtain a xsbti.ComponentProvider, which manages application components. Components are groups of files in the ~/.sbt/boot/ directory and, in this case, the application is sbt. In addition to the base classpath, components in the “extra” component are included on sbt’s classpath.

(Note: the additional components on an application’s classpath are declared by the components property in the [main] section of the launcher configuration file boot.properties.)

Because these components are added to the ~/.sbt/boot/ directory and ~/.sbt/boot/ may be read-only, this can fail. In this case, the user has generally intentionally set sbt up this way, so error recovery is not typically necessary (just a short error message explaining the situation.)

Example of dynamic classpath augmentation 

The following code can be used where a State => State is required, such as in the onLoad setting (described below) or in a command. It adds some files to the “extra” component and reloads sbt if they were not already added. Note that reloading will drop the user’s session state.

def augment(extra: Seq[File])(s: State): State = {
    // Get the component provider
  val cs: xsbti.ComponentProvider = s.configuration.provider.components()

    // Adds the files in 'extra' to the "extra" component
    //   under an exclusive machine-wide lock.
    //   The returned value is 'true' if files were actually copied and 'false'
    //   if the target files already exists (based on name only).
  val copied: Boolean = s.locked(cs.lockFile, cs.addToComponent("extra", extra.toArray))

    // If files were copied, reload so that we use the new classpath.
  if(copied) s.reload else s
}

How can I take action when the project is loaded or unloaded? 

See How to take an action on startup.

Example of project load/unload hooks 

The following example maintains a count of the number of times a project has been loaded and prints that number:

{
  // the key for the current count
  val key = AttributeKey[Int]("loadCount")
  // the State transformer
  val f = (s: State) => {
    val previous = s get key getOrElse 0
    println("Project load count: " + previous)
    s.put(key, previous + 1)
  }
  Global / onLoad := {
    val previous = (Global / onLoad).value
    f compose previous
  }
}

Errors 

On project load, “Reference to uninitialized setting“ 

Setting initializers are executed in order. If the initialization of a setting depends on other settings that has not been initialized, sbt will stop loading.

In this example, we try to append a library to libraryDependencies before it is initialized with an empty sequence.

libraryDependencies += "commons-io" % "commons-io" % "1.4" % "test"

disablePlugins(plugins.IvyPlugin)

To correct this, include the IvyPlugin plugin settings, which includes libraryDependencies := Seq(). So, we just drop the explicit disabling.

libraryDependencies += "commons-io" % "commons-io" % "1.4" % "test"

A more subtle variation of this error occurs when using scoped settings.

// error: Reference to uninitialized setting
settings = Seq(
  libraryDependencies += "commons-io" % "commons-io" % "1.2" % "test",
  fullClasspath := fullClasspath.value.filterNot(_.data.name.contains("commons-io"))
)

This setting varies between the test and compile scopes. The solution is use the scoped setting, both as the input to the initializer, and the setting that we update.

Compile / fullClasspath := (Compile / fullClasspath).value.filterNot(_.data.name.contains("commons-io"))

Dependency Management 

How do I resolve a checksum error? 

This error occurs when the published checksum, such as a sha1 or md5 hash, differs from the checksum computed for a downloaded artifact, such as a jar or pom.xml. An example of such an error is:

[warn]  problem while downloading module descriptor:
https://repo1.maven.org/maven2/commons-fileupload/commons-fileupload/1.2.2/commons-fileupload-1.2.2.pom:
invalid sha1: expected=ad3fda4adc95eb0d061341228cc94845ddb9a6fe computed=0ce5d4a03b07c8b00ab60252e5cacdc708a4e6d8 (1070ms)

The invalid checksum should generally be reported to the repository owner (as was done for the above error). In the meantime, you can temporarily disable checking with the following setting:

checksums in update := Nil

See library management for details.

I’ve added a plugin, and now my cross-compilations fail! 

This problem crops up frequently. Plugins are only published for the Scala version that sbt uses (currently, 2.12). You can still use plugins during cross-compilation, because sbt only looks for a 2.12 version of the plugin.

… unless you specify the plugin in the wrong place!

A typical mistake is to put global plugin definitions in ~/.sbt/plugins.sbt. THIS IS WRONG. .sbt files in ~/.sbt are loaded for each build—that is, for each cross-compilation. So, if you build for Scala 2.11.0, sbt will try to find a version of the plugin that’s compiled for 2.11.0—and it usually won’t. That’s because it doesn’t know the dependency is a plugin.

To tell sbt that the dependency is an sbt plugin, make sure you define your global plugins in a .sbt file in ~/.sbt/plugins/. sbt knows that files in ~/.sbt/plugins are only to be used by sbt itself, not as part of the general build definition. If you define your plugins in a file under that directory, they won’t foul up your cross-compilations. Any file name ending in .sbt will do, but most people use ~/.sbt/plugins/build.sbt or ~/.sbt/plugins/plugins.sbt.

Miscellaneous 

Where can I find plugins for 1.9.8? 

See Community Plugins for a list of currently available plugins.

General Information 

This part of the documentation has project “meta-information” such as where to get help, find source code and how to contribute.

Credits 

sbt was originally created by Mark Harrah (@harrah) in 2008. Most of the fundamental aspects of sbt, such as the Scala incremental compiler, integration with Maven and Ivy dependencies, and parallel task processing were conceived and initially implemented by Mark.

By 2010, when sbt 0.7 came out, many open-source Scala projects were using sbt as their build tool.

Mark joined Typesafe (now Lightbend) in 2011, the year the company was founded. sbt 0.10.0 shipped that same year. Mark remained the maintainer and most active contributor until March 2014, with sbt 0.13.1 as his last release.

Josh Suereth (@jsuereth) at Typesafe became the next maintainer of sbt.

In 2014, Eugene Yokota (@eed3si9n) joined Typesafe to co-lead sbt with Josh. This team carried the 0.13 series through 0.13.5 and started the trajectory to 1.0 as technology previews. By the time of Josh’s departure in 2015, after sbt 0.13.9, they had shipped AutoPlugin, kept sbt 0.13 in shape, and laid groundwork for sbt server.

Grzegorz Kossakowski (@gkossakowski) worked on a better incremental compiler algorithm called “name hashing” during his time on the Scala team at Typesafe. Name hashing became the default incremental compiler in sbt 0.13.6 (2014). Lightbend later commissioned Grzegorz to refine name hashing using a technique called class-based name hashing, which was adopted by Zinc 1. Another notable contribution from Grzegorz was hosting a series of meetups with @WarszawScaLa, and (with his arm in a sling the infamous blank-line problem.

In May 2015, Dale Wijnand (@dwijnand) became a committer from the community after contributing features such as inThisBuild and -=.

From June 2015 to early 2016, Martin Duhem (@Duhemm) joined Typesafe as an intern, working on sbt. During this time, Martin worked on crucial components such as making the compiler bridge configurable for Zinc, and code generation for pseudo case classes (which later became Contraband).

Around this time, Eugene, Martin, and Dale started the sbt 1.x codebase, splitting the code base into multiple modules: sbt/sbt, Zinc 1, sbt/librarymanagement, sbt/util, and sbt/io. The aim was to make Zinc 1, an incremental compiler usable by all build tools.

In August 2016, Dale joined the Tooling team at Lightbend. Dale and Eugene oversaw the releases 0.13.12 through 0.13.16, as well as the development of sbt 1.0.

In spring 2017, the Scala Center participated in the Zinc 1 development effort. Jorge Vicente Cantero (@jvican) has contributed a number of improvements including the fix for the “as seen from” bug that had blocked Zinc 1.

From spring 2018, Ethan Atkins joined the sbt project as a community member, and quickly became the leading contributor to the project. Initially his contribution was implementing Close Watch that uses native code to provide watch service on macOS. He’s worked on various performance related improvements since then including layered ClassLoader, logging rewrite, and native thin client that uses GraalVM native image.

According to git shortlog -sn --no-merges on sbt/sbt, sbt/zinc, sbt/librarymanagement, sbt/util, sbt/io, sbt/contraband, and sbt/website there were 9151 non-merge commits by 318 contributors.

• Mark Harrah 3852
• Eugene Yokota (eed3si9n) 1760
• Dale Wijnand 524
• Josh Suereth 357
• Grzegorz Kossakowski 349
• Martin Duhem 333
• Jorge Vicente Cantero (jvican) 314
• Eugene Vigdorchik 108
• Kenji Yoshida (xuwei-k) 96
• Indrajit Raychaudhuri 90
• Dan Sanduleac 74
• Benjy Weinberger 52
• Max Peng 52
• Jacek Laskowski 40
• Jason Zaugg 40
• Josh Soref 39
• Krzysztof Romanowski 39
• Pierre DAL-PRA 36
• Andrzej Jozwik 33
• Antonio Cunei 30
• Aaron S. Hawley 29
• Guillaume Martres 25
• James Roper 24
• Chua Chee Seng (cheeseng) 24
• Paolo G. Giarrusso 23
• Matej Urbas 22
• Stu Hood 22
• Adriaan Moors 18
• Jean-Rémi Desjardins 16
• Sanjin Sehic 16
• Fedor Korotkov 14
• Andrew Johnson 13
• David Perez 13
• Havoc Pennington 13
• Liang Tang 12
• Peter Vlugter 12
• Taro L. Saito 10
• Paul Phillips 9
• Roberto Tyley 9
• Vojin Jovanovic 9
• William Benton 9
• 杨博 (Yang Bo) 9
• Brian Topping 8
• Bruno Bieth 8
• Johannes Rudolph 8
• KAWACHI Takashi 8
• Ken Kaizu (krrrr38) 8
• Artyom Olshevskiy 7
• Eugene Platonov 7
• Matthew Farwell 7
• Michael Allman 7
• David Pratt 6
• Luca Milanesio 6
• Nepomuk Seiler 6
• Peiyu Wang 6
• Simeon H.K. Fitch 6
• Stephen Samuel 6
• Thierry Treyer 6
• James Earl Douglas 5
• Jean-Remi Desjardins 5
• Miles Sabin 5
• Seth Tisue 5
• qgd 5
• Anthony Whitford 4
• Bardur Arantsson 4
• Ches Martin 4
• Chris Birchall 4
• Daniel C. Sobral 4
• Heikki Vesalainen 4
• Krzysztof Nirski 4
• Lloyd Meta 4
• Michael Schmitz 4
• Orr Sella 4
• Philipp Dörfler 4
• Tim Harper 4
• Vasya Novikov 4
• Vincent Munier 4
• Jürgen Keck (j-keck) 4
• Richard Summerhayes (rasummer) 4
• Adam Warski 3
• Ben McCann 3
• Enno Runne 3
• Eric Bowman 3
• Henrik Engstrom 3
• Ian Forsey 3
• James Ward 3
• Jesse Kinkead 3
• Justin Pihony 3
• Kazuhiro Sera 3
• Krzysztof Borowski 3
• Lars Hupel 3
• Leif Wickland 3
• Lukas Rytz 3
• Max Worgan 3
• Oliver Wickham 3
• Olli Helenius 3
• Roman Timushev 3
• Simon Schäfer 3
• ZhiFeng Hu 3
• daniel-shuy 3
• Roland Schatz 3
• soc 3
• wpitula 3
• Alex Dupre 2
• Alexey Alekhin 2
• Allan Erskine 2
• Alois Cochard 2
• Andreas Flierl 2
• Anthony 2
• Antoine Gourlay 2
• Arnout Engelen 2
• Ben Hutchison 2
• Benjamin Darfler 2
• Brendan W. McAdams 2
• Brennan Saeta 2
• Brian McKenna 2
• Brian Smith 2
• BrianLondon 2
• Charles Feduke 2
• Christian Dedie 2
• Cody Allen 2
• Damien Lecan 2
• David Barri 2
• David Harcombe 2
• David Hotham 2
• Derek Wickern 2
• Eric D. Reichert 2
• Eric J. Christeson 2
• Evgeny Goldin 2
• Evgeny Vereshchagin 2
• Francois Armand (fanf42) 2
• Fred Dubois 2
• Heejong Lee 2
• Henri Kerola 2
• Hideki Ikio 2
• Ikenna Nwaiwu 2
• Ismael Juma 2
• Jakob Odersky 2
• Jan Berkel 2
• Jan Niehusmann 2
• Jarek Sacha 2
• Jens Halm 2
• Joachim Hofer 2
• Joe Barnes 2
• Johan Andrén 2
• Jonas Fonseca 2
• Josh Kalderimis 2
• Juan Manuel Caicedo Carvajal 2
• Justin Kaeser 2
• Konrad Malawski 2
• Lex Spoon 2
• Li Haoyi 2
• Lloyd 2
• Lukasz Piepiora 2
• Marcus Lönnberg 2
• Marko Elezovic 2
• Michael Parrott 2
• Mikael Vallerie 2
• Myyk Seok 2
• Ngoc Dao 2
• Nicolas Rémond 2
• Oscar Vargas Torres 2
• Paul Draper 2
• Paulo “JCranky” Siqueira 2
• Petro Verkhogliad 2
• Piotr Kukielka 2
• Robin Green 2
• Roch Delsalle 2
• Roman Iakovlev 2
• Scott Royston 2
• Simon Hafner 2
• Sukant Hajra 2
• Suzanne Hamilton 2
• Tejas Mandke 2
• Thomas Koch 2
• Thomas Lockney 2
• Tobias Neef 2
• Tomasz Bartczak 2
• Travis 2
• Vitalii Voloshyn 2
• Wei Chen 2
• Wojciech Langiewicz 2
• Xin Ren 2
• Zava 2
• amishak 2
• beolnix 2
• ddworak 2
• drdamour 2
• Eric K Richardson (ekrich) 2
• fsi206914 2
• henry 2
• kaatzee 2
• kalmanb 2
• nau 2
• qvaughan 2
• sam 2
• softprops 2
• tbje 2
• timt 2
• Aaron D. Valade 1
• Alexander Buchholtz 1
• Alexandr Nikitin 1
• Alexandre Archambault 1
• Alexey Levan 1
• Anatoly Fayngelerin 1
• Andrea 1
• Andrew D Bate 1
• Andrew Miller 1
• Ashley Mercer 1
• Bruce Mitchener 1
• Cause Cheng 1
• Cause Chung 1
• Christian Krause 1
• Christophe Vidal 1
• Claudio Bley 1
• Daniel Peebles 1
• Denis T 1
• Devis Lucato 1
• Dmitry Melnichenko 1
• EECOLOR 1
• Edward Samson 1
• Erik Bakker 1
• Erik Bruchez 1
• Ethan 1
• Federico Ragona 1
• Felix Leipold 1
• Geoffroy Couprie 1
• Gerolf Seitz 1
• Gilad Hoch 1
• Gregor Heine 1
• HairyFotr 1
• Heiko Seeberger 1
• Holden Karau 1
• Hussachai Puripunpinyo 1
• Jacques 1
• Jakob Grunig 1
• James Koch 1
• Jan Polák 1
• Jan Ziniewicz 1
• Jisoo Park 1
• Joonas Javanainen 1
• Joscha Feth 1
• Josef Vlach 1
• Joseph Earl 1
• João Costa 1
• Justin Ko 1
• Kamil Kloch 1
• Kazuyoshi Kato 1
• Kevin Scaldeferri 1
• Knut Petter Meen 1
• Krzysztof 1
• Kunihiko Ito 1
• LMnet 1
• Luc Bourlier 1
• Lucas Mogari 1
• Lutz Huehnken 1
• Mal Graty 1
• Marcos Savoury 1
• Marek Żebrowski 1
• Markus Siemens 1
• Martynas Mickevicius 1
• Martynas Mickevičius 1
• Michael Bayne 1
• Michael Ledin 1
• Nathan Hamblen 1
• Nyavro 1
• OlegYch 1
• Olivier ROLAND 1
• Pavel Penkov 1
• Pedro Larroy 1
• Peter Pan 1
• Piotr Kukiełka 1
• Rikard Pavelic 1
• Robert Jacob 1
• Rogach 1
• Sergey Andreev 1
• Shanbin Wang 1
• Shane Hender 1
• Simon Olofsson 1
• Stefan Zeiger 1
• Stephen Duncan Jr 1
• Steve Gury 1
• Sören Brunk 1
• Thomas Grainger 1
• Tim Sheppard 1
• Todor Todorov 1
• Toshiyuki Takahashi 1
• Travis Brown 1
• Tsubasa Irisawa 1
• Victor Hiairrassary 1
• Yasuo Nakanishi 1
• Yoshitaka Fujii 1
• adinath 1
• albuch 1
• cchantep 1
• cdietze 1
• choucri 1
• hokada 1
• joiskov 1
• jozic 1
• jyane 1
• k.bigwheel 1
• kavedaa 1
• mmcbride 1
• pishen tsai 1
• sanjiv sahayam 1
• saturday06 1
• seroperson 1
• slideon 1
• thricejamie 1
• todesking 1
• totem3 1
• upescatore 1
• valydia 1
• walidbenchikha 1
• Wiesław Popielarski 1
• Łukasz Indykiewicz 1

For the details on individual contributions, see Changes.

The following people contributed ideas, documentation, or code to sbt but are not listed above:

• Josh Cough
• Nolan Darilek
• Viktor Klang
• David R. MacIver
• Ross McDonald
• Andrew O’Malley
• Jorge Ortiz
• Mikko Peltonen
• Ray Racine
• Stuart Roebuck
• Harshad RJ
• Tony Sloane
• Francisco Treacy
• Vesa Vilhonen

The sbt ecosystem would not be the same without so many awesome plugins. Here are some of the plugins and their contributors:

• Play Framework by Lightbend (James Roper, Peter Hausel, and many others)
• Scala.js by Sébastien Doeraene, Tobias Schlatter, et al
• sbt-assembly by Eugene Yokota (eed3si9n)
• coursier by Alexandre Archambault
• sbt Native Packager by Nepomuk Seiler (muuki88) and Josh Suereth
• sbt-dependency-graph by Johannes Rudolph
• WartRemover by Claire Neveu and Brian McKenna
• sbt-android by Perry (pfn)
• sbt-revolver by Johannes Rudolph and Mathias (sirthias)
• sbt-docker by Marcus Lönnberg
• tut by Rob Norris (tpolecat)
• sbt-release by Gerolf Seitz
• sbt-jmh by Konrad Malawski (ktoso)
• sbt-updates by Roman Timushev
• xsbt-web-plugin by James Earl Douglas and Artyom Olshevskiy
• sbt-scoverage by Stephen Samuel and Mikko Koponen
• sbt-web by Lightbend (Christopher Hunt, Peter Vlugter, et al)
• sbt-buildinfo by Eugene Yokota (eed3si9n)
• sbt-pack by Taro L. Saito (xerial)
• sbt-onejar by Jason Zaugg (retronym)
• sbt-git by Josh Suereth
• sbt-scalariform by Heiko Seeberger, Daniel Trinh, et al
• ensime-sbt by Sam Halliday (fommil)
• sbt-fresh by Heiko Seeberger
• sbt-web-scalajs by Vincent Munier
• sbt-sonatype by Taro L. Saito (xerial)
• sbt-sublime by Orr Sella
• sbt-errors-summary by Martin Duhem
• sbt-bintray by Doug Tangren (softprops)
• Migration Manager by Lightbend (Mirco Dotta, Seth Tisue, et al)
• sbt-protobuf by Gerolf Seitz and Kenji Yoshida (xuwei-k)
• sbt-site by Jonas Fonseca, Josh Suereth, et al
• sbt-doctest by KAWACHI Takashi
• sbt-robovm by Jan Polák
• scalastyle-sbt-plugin by Matthew Farwell
• sbt-microsites by 47 Degrees (Juan Pedro Moreno, Javier de Silóniz Sandino, et al)
• sbt-header by Heiko Seeberger and Benedikt Ritter
• sbt-groll by Heiko Seeberger
• sbt-ctags by Cody Allen
• sbt-aws-lambda by Gilt (Brendan St John, et al)
• sbt-heroku by Heroku (Joe Kutner)
• sbt-dynver by Dale Wijnand
• sbt-unidoc by Eugene Yokota and Peter Vlugter
• sbt-docker-compose by Tapad (Kurt Kopchik et al)
• sbt-coveralls by Ian Forsey and Stephen Samuel
• gatling-sbt by Pierre Dal-Pra
• sbt-boilerplate by Johannes Rudolph
• fm-sbt-s3-resolver by Tim Underwood
• sbt-reactjs by Dan Di Spaltro
• sbt-scalabuff by Aloïs Cochard
• sbt-pgp by Josh Suereth
• jacoco4sbt by Joachim Hofer
• sbt-s3-resolver by Alexey Alekhin (laughedelic)
• sbt-maven-plugin by Shiva Wu
• sbt-newrelic by Gilt (Gary Coady et al)
• naptime by Coursera (Brennan Saeta, Bryan Kane et al)
• neo-sbt-scalafmt by Lucid Software (Paul Draper et al)
• Courier by Coursera (Joe Betz et al)
• sbt-optimizer by Johannes Rudolph
• sbt-appengine by Eugene Yokota (eed3si9n) and Yasushi Abe
• sbt/sbt-ghpages by Josh Suereth
• kotlin-plugin by Perry (pfn)
• sbt-avro by Juan Manuel Caicedo Carvajal (cavorite), Ben McCann, et al
• sbt-aspectj by Lightbend (Peter Vlugter et al)
• sbt-crossproject Denys Shabalin and Guillaume Massé
• sbt-scapegoat by Stephen Samuel
• sbt-dependency-graph-sugar by Gilt (Brendan St John et al)
• sbt-aether-deploy by Arktekk (Erlend Hamnaberg et al)
• sbt-spark-submit by Forest Fang
• sbt-proguard by Lightbend (Peter Vlugter et al)
• Jenkins CI sbt plugin by Uzi Landsmann
• sbt-quickfix by Dave Cleaver
• sbt-growl-plugin Doug Tangren (softprops)
• sbt-dependency-check by Alexander v. Buchholtz
• sbt-structure by JetBrains (Justin Kaeser et al)
• sbt-typescript by Brandon Arp
• sbt-javacv by Bytedeco (Lloyd Chan et al)
• sbt-stats by Orr Sella
• sbt-rig by Verizon (Timothy Perrett et al)
• sbt-swagger-codegen by UniCredit (Andrea Peruffo, Francesco MDE, et al)
• sbt-pom-reader by Josh Suereth
• sbt-class-diagram by Kenji Yoshida (xuwei-k)

Kudos also to people who have answered questions on Stack Overflow (Jacek Laskowski, Lukasz Piepiora, et al) and sbt Gitter channel, and many who have reported issues and contributed ideas on GitHub.

Thank you all.

Community Plugins 

sbt Organization 

The sbt organization is available for use by any sbt plugin. Developers who contribute their plugins into the community organization will still retain control over their repository and its access. The goal of the sbt organization is to organize sbt software into one central location.

A side benefit to using the sbt organization for projects is that you can use gh-pages to host websites under the https://www.scala-sbt.org domain.

The sbt autoplugin giter8 template is a good place to start. This sets up a new sbt plugin project appropriately. The generated README includes a summary of the steps for publishing a new community plugin.

Community Ivy Repository 

Lightbend has provided a freely available Ivy Repository for sbt projects to use. This Ivy repository is mirrored from the freely available Bintray service. If you’d like to submit your plugin, please follow these instructions: Bintray For Plugins.

Cross building plugins from sbt 0.13 

See Cross Build Plugins.

Plugins available for sbt 1.0 (including RC-x) 

[Edit] this page to submit a pull request that adds your plugin to the list.

Code formatter plugins 

• sbt-scalafmt: code formatting using Scalafmt.
• sbt-scalariform: code formatting using Scalariform.
• neo-sbt-scalafmt: code formatting using Scalafmt.
• sbt-java-formatter: code formatting for Java sources.
• sbt-source-format: code formatting for Java and clang (c/c++/objc) sources.
• safety-plugin: Enforce the use of style rules across your company

Documentation plugins 

• tut: documentation and tutorial generator.
• Laika: Transform Markdown or reStructuredText into HTML or PDF with Templating.
• sbt-site: site generator.
• sbt-microsites: generate and publish microsites using Jekyll.
• sbt-unidoc: create unified API documentation across subprojects.
• sbt-ghpages: publish generated sites to GitHub pages.
• sbt-class-diagram: generate class diagrams from Scala source code.
• sbt-api-mappings: generate Scaladoc apiMappings for common Scala libraries.
• literator: generate literate-style markdown docs from your sources.
• sbt-example:  generate ScalaTest test suites from examples in Scaladoc.
• sbt-delombok:  delombok Java sources files that contain Lombok annotations to make Javadoc contain Lombok-generated classes and methods.
• sbt-alldocs: collect all the docs for a project and dependencies into a single folder.
• sbt-apidoc: A port of apidocjs to sbt, to document REST Api.
• sbt-github-pages (docs): publish a website to GitHub Pages with minimal effort - works well with GitHub Actions.
• sbt-docusaur (docs): build a website using Docusaurus and publish to GitHub Pages with minimal effort - works well with GitHub Actions.
• sbt-hl-compiler: compile the code snippets from documentation (to keep it consistent).
• sbt-scaladoc-compiler: compile the code snippets included in Scaladoc comments.

One jar plugins 

• sbt-assembly: create fat JARs.

Release plugins 

• sbt-native-packager (docs): build native packages (RPM, .deb etc) for your projects.
• sbt-pack: create runnable distributions for your projects.
• sbt-bintray: publish artefacts to Bintray.
• sbt-sonatype: publish artefacts to Maven Central.
• sbt-release: create a customizable release process.
• sbt-pgp: sign artefacts using PGP/GPG and manage signing keys.
• sbt-docker: create and push Docker images.
• sbt-aether-deploy: publish artefacts using Eclipse Aether.
• sbt-rig: opinionated common release steps.
• sbt-s3: manage objects on Amazon S3.
• sbt-osgi: create OSGi bundles.
• sbt-github-release: publish Github releases.
• sbt-hadoop: publish artifacts to the Hadoop Distributed File System (HDFS).
• sbt-publish-more: publish artifacts to several repositories
• sbt-deploy: create deployable fat JARs.
• sbt-release-fossil: enhances sbt-release to support Fossil repositories
• sbt-autoversion: automatically set your next version bump based on patterns of your commit message since last release.
• sbt-gcs: manage objects on Google Cloud Storage.
• sbt-sourcebundler: merge all source code into one scala file.
• sbt-kubeyml: Create a typesafe kubernetes Deployment based on your project settings
• sbt-k8s: Create any manifest or use provided cookbooks using scala-k8s library
• sbt-release-notes: provide a Release Step for sbt-release to automatically update the release notes file.

Deployment integration plugins 

• sbt-heroku: deploy applications directly to Heroku.
• sbt-docker-compose: launch Docker images using docker compose.
• sbt-appengine deploy your webapp to Google App Engine.
• sbt-marathon: deploy applications on Apache Mesos using the Marathon framework.
• sbt-riotctl: deploy applications as systemd services directly to a Raspberry Pi, ensuring dependencies (e.g. wiringpi) are met.
• sbt-kind: load built docker images into a kind cluster.

Utility and system plugins 

• sbt-revolver: auto-restart forked JVMs on update.
• sbt-conscript (docs): distribute apps using GitHub and Maven Central.
• sbt-git: run git commands from sbt.
• sbt-errors-summary: show a summary of compilation errors.
• MiMa: binary compatibility management for Scala libraries.
• sbt-groll: navigate git history inside sbt.
• sbt-dynver: set project version dynamically from git metadata.
• sbt-prompt: add promptlets and themes to your sbt prompt.
• sbt-crossproject: cross-build Scala, Scala.js and Scala Native.
• sbt-proguard: run ProGuard on compiled sources.
• sbt-structure: extract project structure in XML format.
• sbt-jni: helpers for working with projects that use JNI.
• sbt-jol: inspect OpenJDK Java Object Layout from sbt.
• sbt-musical: control iTunes from sbt (Mac only).
• sbt-travisci: integration with Travis CI.
• horder: cache compilation artefacts for future builds.
• sbt-javaagent: add Java agents to projects.
• sbt-jshell: Java REPL for sbt.
• sbt-check: compile up to, and including, the typer phase.
• sbt-mima-version-check: Automate which Mima Versions to Check
• sbt-tmpfs: utilize tmpfs to speed up builds.
• sbt-sh: run shell commands from sbt.
• sbt-ammonite-classpath: export classpath for Ammonite and Almond.
• sbt-version-scheme-enforcer-plugin: Derive Mima settings for your library from your declared versionScheme. This supports Early SemVer, Strict SemVer, and Package Versioning Policy (PVP).

IDE integration plugins 

• sbteclipse: Eclipse project definition generator.
• sbt-sublime: Sublime Text project generator.

Test plugins 

• scripted: integration testing for sbt plugins.
• sbt-jmh: run Java Microbenchmark Harness (JMH) benchmarks from sbt.
• sbt-doctest: generate and run tests from Scaladoc comments.
• gatling-sbt: performance and load-testing using Gatling.
• sbt-multi-jvm: run tests using multiple JVMs.
• sbt-scalaprops: scalaprops property-based testing integration.
• sbt-testng: TestNG framework integration.
• sbt-jcstress: Java Concurrency Stress Test (jcstress) integration.
• sbt-stryker4s: Test your tests with mutation testing.
• sbt-cached-ci: Incremental sbt builds for CI environments.

Library dependency plugins 

• coursier: pure Scala dependency fetcher.
• sbt-dependency-graph: create dependency graphs using GraphML, graphviz or ASCII.
• sbt-updates: list updated versions of dependencies.
• fm-sbt-s3-resolver: resolve and publish artefacts using Amazon S3.
• sbt-s3-resolver: resolve dependencies using Amazon S3.
• sbt-dependency-check: check dependencies for known vulnerabilities/CVEs.
• sbt-lock: create a lock file containing explicit sbt dependencies.
• sbt-license-report: generate reports of licenses used by dependencies.
• sbt-duplicates-finder: detect class and resources conflicting in your project’s classpath.
• sbt-google-cloud-storage: resolver and publisher for Google Cloud Storage.
• sbt-trace: find traces of the client or library usage in other projects.
• safety-plugin: Enforce the use of specified versions of dependencies across your company
• sbt-dependency-lock: generate dependency lockfiles and check for changes at build time.
• sbt-unzip: Extract zip dependencies where you want in your project.

Web and frontend development plugins 

• Play Framework: reactive web framework for Scala and Java.
• Scala.js: Scala to JavaScript compiler.
• xsbt-web-plugin: Servlet support.
• sbt-web: library for building sbt plugins for the web.
• sbt-web-scalajs: use Scala.js with any web server.
• sbt-less: Less CSS compilation support.
• sbt-js-engine: support for sbt plugins that use JavaScript.
• sbt-typescript: TypeScript compilation support.
• sbt-uglify: JavaScript minifier using UglifyJS.
• sbt-terser: JavaScript (ES6+) minifier using terser.
• sbt-digest: generate checksums of assets.
• sbt-scalatra: build and run Scalatra apps.
• sbt-scala-js-map: Configure source mapping for Scala.js projects hosted on Github.
• sbt-gzip: gzip compressor for assets.
• sbt-stylus: Stylus stylesheet compiler.
• sbt-hepek: Render static websites directly from Scala code.
• sbt-puresass: sbt-web plugin for Sass styles compilation.
• sbt-scala-ts; generates TypeScript declaration files from ScalaJS sources and outputs Node modules.

Database plugins 

• scalikejdbc-mapper-generator: Scala code generator from database schema.
• sbt-dynamodb: run a local Amazon DynamoDB test instance from sbt.
• sbt-migrations: database migrations manager.

Framework-specific plugins 

• sbt-newrelic: NewRelic support for artefacts built with sbt-native-packager.
• sbt-spark: Spark application configurator.
• sbt-api-builder: support for ApiBuilder from within sbt’s shell.

Code generator plugins 

• sbt-buildinfo: generate Scala code from SBT setting keys.
• sbt-scalaxb: generate model classes from XML schemas and WSDL.
• sbt-protobuf: protobuf code generator.
• sbt-header: auto-generate source code file headers (such as copyright notices).
• sbt-boilerplate: TupleX and FunctionX boilerplate code generator.
• sbt-avro: Apache Avro schema and protocol generator.
• sbt-aspectj: AspectJ weaving for sbt.
• sbt-protoc: protobuf code generator using protoc.
• sbt-contraband (docs): generate pseudo-case classes from GraphQL schemas.
• sbt-antlr4: run ANTLR v4 from sbt.
• sbt-sql: generate model classes from SQL.
• sbt-partial-unification: enable partial unification support in Scala (SI-2712).
• sbt-i18n: transform your i18n bundles into Scala code.
• sbt-lit: build literate code with sbt.
• sbt-embedded-files: generate Scala objects containing the contents of glob-specified files as strings or byte-arrays.
• sbt-scala-ts: generate TypeScript code according compiled Scala types (case class, trait, object, …).

Static code analysis plugins 

• wartremover: flexible Scala linting tool.
• scalastyle-sbt-plugin: code style checking using Scalastyle.
• sbt-scapegoat: static analysis using Scapegoat.
• sbt-stats: generate source code statistics (lines of code etc).
• sbt-scalafix: refactoring and linting tool for Scala using Scalafix.
• sbt-explicit-dependencies: check that you have declared all your library dependencies correctly
• sbt-taglist: find tags within source files (such as TODO and FIXME).
• sbt-rewarn: always display compilation warnings, despite the incremental compilation.
• sbt-jcheckstyle: Java code style checking using Checkstyle.
• sbt-sonar: integration with SonarQube.
• sbt-scala2plantuml: generates PlantUML diagrams from Scala code.

Code coverage plugins 

• sbt-scoverage: Scala code coverage using Scoverage.
• sbt-jacoco: Scala and Java code coverage using JaCoCo.

Create new project plugins 

• sbt-fresh: create an opinionated fresh sbt project.

In-house plugins 

• sbt-houserules: houserules settings for sbt modules.

Verification plugins 

• sbt-stainless: verify Scala or Dotty code using stainless.

Language support plugins 

• sbt-frege: build Frege code with sbt.
• sbt-cc: compile C and C++ source files with sbt.

Community Repository Policy 

The community repository has the following guideline for artifacts published to it:

1. All published artifacts are the authors own work or have an appropriate license which grants distribution rights.
2. All published artifacts come from open source projects, that have an open patch acceptance policy.
3. All published artifacts are placed under an organization in a DNS domain for which you have the permission to use or are an owner (scala-sbt.org is available for sbt plugins).
4. All published artifacts are signed by a committer of the project (coming soon).

Bintray For Plugins 

We no longer use Bintray to host plugins.

First and foremost, we would like to thank JFrog for their continued support of sbt project and the Scala ecosystem. Between 2014 and April, 2021 sbt hosted its community plugin repository on bintray.com/sbt.

When JFrog sunsetted their Bintray product, they have proactively contacted us and granted Scala Center open source sponsorship that allows us to use an online Artifactory instance.

As of 2021-04-18, we have migrated all sbt plugins and sbt 0.13 artifacts to the Artifactory instance, and redirected https://repo.scala-sbt.org/scalasbt/ to point to it as well, so existing builds should continue to work without making any changes today and after May 1st. For plugin hosting, we will operate this as a read-only repository. Any new plugin releases should migrate to using Sonatype OSS.

Using Sonatype 

Deploying to sonatype is easy! Just follow these simple steps:

Sonatype setup 

The reference process for configuring and publishing to Sonatype is described in their OSSRH Guide. In short, you need two publicly available URLs:

• the website of the project e.g. https://github.com/sonatype/nexus-public
• the project’s source code e.g. https://github.com/sonatype/nexus-public.git

The OSSRH Guide walks you through the required process of setting up the account with Sonatype. It’s as simple as creating a Sonatype's JIRA account and then a New Project ticket. When creating the account, try to use the same domain in your email address that the project is hosted on. It makes it easier for Sonatype to validate the relationship with the groupId requested in the ticket, but it is not the only method used to confirm the ownership.

Creation of the New Project ticket is as simple as:

• providing the name of the library in the ticket’s subject,
• naming the groupId for distributing the library (make sure it matches the root package of your code). Sonatype provides additional hints on choosing the right groupId for publishing your library in Choosing your coordinates guide.
• providing the SCM and Project URLs to the source code and homepage of the library.

After creating your Sonatype account on JIRA, you can log in to the Nexus Repository Manager using the same credentials, although this is not required in the guide, it can be helpful later to check on published artifacts.

Note: Sonatype advises that responding to a New Project ticket might take up to two business days, but in my case it was a few minutes.

sbt setup 

To address Sonatype’s requirements for publishing to the central repository and to simplify the publishing process, you can use two community plugins. The sbt-pgp plugin can sign the files with GPG/PGP. (Optionally sbt-sonatype can publish to a Sonatype repository nicer.)

step 1: PGP Signatures 

Follow Working with PGP Signatures.

First, you should install GnuPG, and verify the version:

$ gpg --version
gpg (GnuPG/MacGPG2) 2.2.8
libgcrypt 1.8.3
Copyright (C) 2018 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>

Next generate a key:

$ gpg --gen-key

List the keys:

$ gpg --list-keys

/home/foo/.gnupg/pubring.gpg
------------------------------

pub   rsa4096 2018-08-22 [SC]
      1234517530FB96F147C6A146A326F592D39AAAAA
uid           [ultimate] your name <[email protected]>
sub   rsa4096 2018-08-22 [E]

Distribute the key:

$ gpg --keyserver keyserver.ubuntu.com --send-keys 1234517530FB96F147C6A146A326F592D39AAAAA

step 2: sbt-pgp 

With the PGP key you want to use, you can sign the artifacts you want to publish to the Sonatype repository with the sbt-pgp plugin. Follow the instructions for the plugin and you’ll have PGP signed artifacts in no time.

In short, add the following line to your ~/.sbt/1.0/plugins/gpg.sbt file to enable it globally for SBT projects:

addSbtPlugin("com.github.sbt" % "sbt-pgp" % "2.1.2")

Note: The plugin is a solution to sign artifacts. It works with the GPG command line tool.

Make sure that the gpg command is in PATH available to the sbt.

step 3: Credentials 

The credentials for your Sonatype OSSRH account need to be stored somewhere safe (e.g. NOT in the repository). Common convention is a $HOME/.sbt/1.0/sonatype.sbt file, with the following:

credentials += Credentials(Path.userHome / ".sbt" / "sonatype_credentials")

Next create a file ~/.sbt/sonatype_credentials:

realm=Sonatype Nexus Repository Manager
host=oss.sonatype.org
user=<your username>
password=<your password>

Note: The first two strings must be "Sonatype Nexus Repository Manager" and "oss.sonatype.org" for Coursier to use the credentials. If you are using a new OSSRH account created after February 2021, use "s01.oss.sonatype.org" instead of "oss.sonatype.org"

step 4: Configure build.sbt 

To publish to a maven repository, you’ll need to configure a few settings so that the correct metadata is generated.

Add these settings at the end of build.sbt or a separate publish.sbt:

ThisBuild / organization := "com.example.project2"
ThisBuild / organizationName := "example"
ThisBuild / organizationHomepage := Some(url("http://example.com/"))

ThisBuild / scmInfo := Some(
  ScmInfo(
    url("https://github.com/your-account/your-project"),
    "scm:[email protected]:your-account/your-project.git"
  )
)
ThisBuild / developers := List(
  Developer(
    id = "Your identifier",
    name = "Your Name",
    email = "your@email",
    url = url("http://your.url")
  )
)

ThisBuild / description := "Some description about your project."
ThisBuild / licenses := List(
  "Apache 2" -> new URL("http://www.apache.org/licenses/LICENSE-2.0.txt")
)
ThisBuild / homepage := Some(url("https://github.com/example/project"))

// Remove all additional repository other than Maven Central from POM
ThisBuild / pomIncludeRepository := { _ => false }
ThisBuild / publishTo := {
  // For accounts created after Feb 2021:
  // val nexus = "https://s01.oss.sonatype.org/"
  val nexus = "https://oss.sonatype.org/"
  if (isSnapshot.value) Some("snapshots" at nexus + "content/repositories/snapshots")
  else Some("releases" at nexus + "service/local/staging/deploy/maven2")
}
ThisBuild / publishMavenStyle := true

The full format of a pom.xml (an end product of the project configuration used by Maven) file is outlined here. You can add more data to it with the pomExtra option in build.sbt.

step 5: Publishing 

From sbt shell run:

> publishSigned

Check the published artifacts in the Nexus Repository Manager (same login as Sonatype’s Jira account).

Close the staging repository and promote the release to central, by hitting “Close” button, then “Release” button.

Optional steps 

sbt-sonatype 

Note: sbt-sonatype is a third-party plugin meaning it is not covered by Lightbend subscription.

To simplify the usage of the Sonatype’s Nexus, add the following line to project/plugins.sbt to import the sbt-sonatype plugin to your project:

addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "3.9.13")

This plugin will facilitate the publishing process, but in short, these are the main steps for publishing the libraries to the repository:

1. Create a new staging repository: sonatypeOpen "your groupId" "Some staging name"
2. Sign and publish the library to the staging repository: publishSigned
3. You can and should check the published artifacts in the Nexus Repository Manager (same login as Sonatype’s Jira account)
4. Close the staging repository and promote the release to central: sonatypeRelease

Below are some important keys to take note of when using this plugin. Read here for more information.

// This becomes a simplified version of the above key.
publishTo := sonatypePublishToBundle.value
// Set this to the same value set as your credential files host.
sonatypeCredentialHost := "oss.sonatype.org"
// Set this to the repository to publish to using `s01.oss.sonatype.org`
// for accounts created after Feb. 2021.
sonatypeRepository := "https://oss.sonatype.org/service/local"

After publishing you have to follow the release workflow of Nexus.

Note: the sbt-sonatype plugin can also be used to publish to other non-sonatype repositories

Publishing tips 

Use staged releases to test across large projects of independent releases before pushing the full project.

Note: An error message of PGPException: checksum mismatch at 0 of 20 indicates that you got the passphrase wrong. We have found at least on OS X that there may be issues with characters outside the 7-bit ASCII range (e.g. Umlauts). If you are absolutely sure that you typed the right phrase and the error doesn’t disappear, try changing the passphrase.

Note: If you are using a new OSSRH account created after February 2021, use "s01.oss.sonatype.org" instead of "oss.sonatype.org"

Integrate with the release process 

Note: sbt-release is a third-party plugin meaning it is not covered by Lightbend subscription.

To automate the publishing approach above with the sbt-release plugin, you should simply add the publishing commands as steps in the releaseProcess task:

...
releaseStepCommand("sonatypeOpen \"your groupId\" \"Some staging name\""),
...
releaseStepCommand("publishSigned"),
...
releaseStepCommand("sonatypeRelease"),
...

Contributing to sbt 

Below is a running list of potential areas of contribution. This list may become out of date quickly, so you may want to check on the sbt-dev mailing list if you are interested in a specific topic.

1. There are plenty of possible visualization and analysis opportunities.

   • ’compile’ produces an Analysis of the source code containing

     • Source dependencies
     • Inter-project source dependencies
     • Binary dependencies (jars + class files)
     • data structure representing the API of the source code There is some code already for generating dot files that isn’t hooked up, but graphing dependencies and inheritance relationships is a general area of work.
   • ’update’ produces an [Update Report][Update-Report] mapping Configuration/ModuleID/Artifact to the retrieved File
   • Ivy produces more detailed XML reports on dependencies. These come with an XSL stylesheet to view them, but this does not scale to large numbers of dependencies. Working on this is pretty straightforward: the XML files are created in ~/.ivy2 and the .xsl and .css are there as well, so you don’t even need to work with sbt. Other approaches described in the email thread
   • Tasks are a combination of static and dynamic graphs and it would be useful to view the graph of a run
   • Settings are a static graph and there is code to generate the dot files, but isn’t hooked up anywhere.
2. There is support for dependencies on external projects, like on GitHub. To be more useful, this should support being able to update the dependencies. It is also easy to extend this to other ways of retrieving projects. Support for svn and hg was a recent contribution, for example.
3. If you like parsers, sbt commands and input tasks are written using custom parser combinators that provide tab completion and error handling. Among other things, the efficiency could be improved.
4. The javap task hasn’t been reintegrated
5. Implement enhanced 0.11-style warn/debug/info/error/trace commands. Currently, you set it like any other setting:

set logLevel := Level.Warn

or : set Test / logLevel := Level.Warn

You could make commands that wrap this, like:

warn Test/run

Also, trace is currently an integer, but should really be an abstract data type.

1. Each sbt version has more aggressive incremental compilation and reproducing bugs can be difficult. It would be helpful to have a mode that generates a diff between successive compilations and records the options passed to scalac. This could be replayed or inspected to try to find the cause.

Documentation 

1. There’s a lot to do with this documentation. If you check it out from git, there’s a directory called Dormant with some content that needs going through.
2. the main page mentions external project references (e.g. to a git repository) but doesn’t have anything to link to that explains how to use those.
3. API docs are much needed.
4. Find useful answers or types/methods/values in the other docs, and pull references to them up into /faq or /Name-Index so people can find the docs. In general the /faq should feel a bit more like a bunch of pointers into the regular docs, rather than an alternative to the docs.

5. A lot of the pages could probably have better names, and/or little

   2-4 word blurbs to the right of them in the sidebar.

Changes 

These are changes made in each sbt release.

Migrating from sbt 0.13.x 

Migrating case class .copy(...) 

Many of the case classes are replaced with pseudo case classes generated using Contraband. Migrate .copy(foo = xxx) to withFoo(xxx). Suppose you have m: ModuleID, and you’re currently calling m.copy(revision = "1.0.1"). Here how you can migrate it:

m.withRevision("1.0.1")

SbtPlugin 

sbt 0.13, sbt 1.0, and sbt 1.1 required sbtPlugin setting and scripted plugin to develop an sbt plugin. sbt 1.2.1 combined both into SbtPlugin plugin.

Remove scripted-plugin from project/plugins.sbt, and just use:

lazy val root = (project in file("."))
  .enablePlugins(SbtPlugin)

sbt version specific source directory 

If you are cross building an sbt plugin, one escape hatch we have is sbt version specific source directory src/main/scala-sbt-0.13 and src/main/scala-sbt-1.0. In there you can define an object named PluginCompat as follows:

package sbtfoo

import sbt._
import Keys._

object PluginCompat {
  type UpdateConfiguration = sbt.librarymanagement.UpdateConfiguration

  def subMissingOk(c: UpdateConfiguration, ok: Boolean): UpdateConfiguration =
    c.withMissingOk(ok)
}

Now subMissingOk(...) function can be implemented in sbt version specific way.

Migrating to slash syntax 

In sbt 0.13 keys were scoped with 2 different syntaxes: one for sbt’s shell and one for in code.

• sbt 0.13 shell: <project-id>/config:intask::key
• sbt 0.13 code: key in (<project-id>, Config, intask)

Starting sbt 1.1.0, the syntax for scoping keys has been unified for both the shell and the build definitions to the slash syntax as follows:

• <project-id> / Config / intask / key

Here are some examples:

version in ThisBuild := "1.0.0-SNAPSHOT"

lazy val root = (project in file("."))
  .settings(
    name := "hello",
    scalacOptions in Compile += "-Xlint",
    scalacOptions in (Compile, console) --= Seq("-Ywarn-unused", "-Ywarn-unused-import"),
    fork in Test := true
  )

They are now written as:

ThisBuild / version := "1.0.0-SNAPSHOT"

lazy val root = (project in file("."))
  .settings(
    name := "hello",
    Compile / scalacOptions += "-Xlint",
    Compile / console / scalacOptions --= Seq("-Ywarn-unused", "-Ywarn-unused-import"),
    Test / fork := true
  )

And now the same syntax in sbt’s shell:

sbt:hello> name
[info] hello
sbt:hello> ThisBuild / version
[info] 1.0.0-SNAPSHOT
sbt:hello> show Compile / scalacOptions
[info] * -Xlint
sbt:hello> show Compile / console / scalacOptions
[info] * -Xlint
sbt:hello> Test / fork
[info] true

There’s a syntactic Scalafix rule for unified slash syntax to semi-automatically rewrite existing sbt 0.13 syntax to the slash syntax. Currently it requires the use of scalafix CLI and it’s not very precise (because it’s a syntactic rule that only looks at the shape of the code) but it gets most of the job done.

$ scalafix --rules=https://gist.githubusercontent.com/eed3si9n/57e83f5330592d968ce49f0d5030d4d5/raw/7f576f16a90e432baa49911c9a66204c354947bb/Sbt0_13BuildSyntax.scala *.sbt project/*.scala

Migrating from sbt 0.12 style 

Before sbt 0.13 (sbt 0.9 to 0.12) it was very common to see in builds the usage of three aspects of sbt:

• the key dependency operators: <<=, <+=, <++=
• the tuple enrichments (apply and map) for TaskKey’s and SettingKey’s (eg. (foo, bar) map { (f, b) => ... })
• the use of Build trait in project/Build.scala

The release of sbt 0.13 (which was over 3 years ago!) introduced the .value DSL which allowed for much easier to read and write code, effectively making the first two aspects redundant and they were removed from the official documentation.

Similarly, sbt 0.13’s introduction of multi-project build.sbt made the Build trait redundant. In addition, the auto plugin feature that’s now standard in sbt 0.13 enabled automatic sorting of plugin settings and auto import feature, but it made Build.scala more difficult to maintain.

As they are removed in sbt 1.0.0, and here we’ll help guide you to how to migrate your code.

Migrating sbt 0.12 style operators 

With simple expressions such as:

a <<= aTaskDef
b <+= bTaskDef
c <++= cTaskDefs

it is sufficient to replace them with the equivalent:

a := aTaskDef.value
b += bTaskDef.value
c ++= cTaskDefs.value

Migrating from the tuple enrichments 

As mentioned above, there are two tuple enrichments .apply and .map. The difference used to be for whether you’re defining a setting for a SettingKey or a TaskKey, you use .apply for the former and .map for the latter:

val sett1 = settingKey[String]("SettingKey 1")
val sett2 = settingKey[String]("SettingKey 2")
val sett3 = settingKey[String]("SettingKey 3")

val task1 = taskKey[String]("TaskKey 1")
val task2 = taskKey[String]("TaskKey 2")
val task3 = taskKey[String]("TaskKey 3")
val task4 = taskKey[String]("TaskKey 4")

sett1 := "s1"
sett2 := "s2"
sett3 <<= (sett1, sett2)(_ + _)

task1 := { println("t1"); "t1" }
task2 := { println("t2"); "t2" }
task3 <<= (task1, task2) map { (t1, t2) => println(t1 + t2); t1 + t2 }
task4 <<= (sett1, sett2) map { (s1, s2) => println(s1 + s2); s1 + s2 }

(Remember you can define tasks in terms of settings, but not the other way round)

With the .value DSL you don’t have to know or remember if your key is a SettingKey or a TaskKey:

sett1 := "s1"
sett2 := "s2"
sett3 := sett1.value + sett2.value

task1 := { println("t1"); "t1" }
task2 := { println("t2"); "t2" }
task3 := { println(task1.value + task2.value); task1.value + task2.value }
task4 := { println(sett1.value + sett2.value); sett1.value + sett2.value }

Migrating when using .dependsOn, .triggeredBy or .runBefore 

When instead calling .dependsOn, instead of:

a <<= a dependsOn b

define it as:

a := (a dependsOn b).value

Note: You’ll need to use the <<= operator with .triggeredBy and .runBefore in sbt 0.13.13 and earlier due to issue #1444.

Migrating when you need to set Tasks 

For keys such as sourceGenerators and resourceGenerators which use sbt’s Task type:

val sourceGenerators =
  settingKey[Seq[Task[Seq[File]]]]("List of tasks that generate sources")
val resourceGenerators =
  settingKey[Seq[Task[Seq[File]]]]("List of tasks that generate resources")

Where you previous would define things as:

sourceGenerators in Compile <+= buildInfo

for sbt 1, you define them as:

Compile / sourceGenerators += buildInfo

or in general,

Compile / sourceGenerators += Def.task { List(file1, file2) }

Migrating with InputKey 

When using InputKey instead of:

run <<= docsRunSetting

when migrating you mustn’t use .value but .evaluated:

run := docsRunSetting.evaluated

Migrating from the Build trait 

With Build trait based build such as:

import sbt._
import Keys._
import xyz.XyzPlugin.autoImport._

object HelloBuild extends Build {
  val shared = Defaults.defaultSettings ++ xyz.XyzPlugin.projectSettings ++ Seq(
    organization := "com.example",
    version      := "0.1.0",
    scalaVersion := "2.12.18")

  lazy val hello =
    Project("Hello", file("."),
      settings = shared ++ Seq(
        xyzSkipWrite := true)
    ).aggregate(core)

  lazy val core =
    Project("hello-core", file("core"),
      settings = shared ++ Seq(
        description := "Core interfaces",
        libraryDependencies ++= scalaXml.value)
    )

  def scalaXml = Def.setting {
    scalaBinaryVersion.value match {
      case "2.10" => Nil
      case _      => ("org.scala-lang.modules" %% "scala-xml" % "1.0.6") :: Nil
    }
  }
}

You can migrate to build.sbt:

val shared = Seq(
  organization := "com.example",
  version      := "0.1.0",
  scalaVersion := "2.12.18"
)

lazy val helloRoot = (project in file("."))
  .aggregate(core)
  .enablePlugins(XyzPlugin)
  .settings(
    shared,
    name := "Hello",
    xyzSkipWrite := true
  )

lazy val core = (project in file("core"))
  .enablePlugins(XyzPlugin)
  .settings(
    shared,
    name := "hello-core",
    description := "Core interfaces",
    libraryDependencies ++= scalaXml.value
  )

def scalaXml = Def.setting {
  scalaBinaryVersion.value match {
    case "2.10" => Nil
    case _      => ("org.scala-lang.modules" %% "scala-xml" % "1.0.6") :: Nil
  }
}

1. Rename project/Build.scala to build.sbt.
2. Remove import statements import sbt._, import Keys._, and any auto imports.
3. Move all of the inner definitions (like shared, helloRoot, etc) out of the object HelloBuild, and remove HelloBuild.
4. Change Project(...) to (project in file("x")) style, and call its settings(...) method to pass in the settings. This is so the auto plugins can reorder their setting sequence based on the plugin dependencies. name setting should be set to keep the old names.
5. Remove Defaults.defaultSettings out of shared since these settings are already set by the built-in auto plugins, also remove xyz.XyzPlugin.projectSettings out of shared and call enablePlugins(XyzPlugin) instead.

Note: Build traits is deprecated, but you can still use project/*.scala file to organize your build and/or define ad-hoc plugins. See Organizing the build.

Migrating from Resolver.withDefaultResolvers 

In 0.13.x, you use other repositories instead of the Maven Central repository:

externalResolvers := Resolver.withDefaultResolvers(resolvers.value, mavenCentral = false)

After 1.x, withDefaultResolvers was renamed to combineDefaultResolvers. In the meantime, one of the parameters, userResolvers, was changed to Vector instead of Seq.

• You can use toVector to help migration.

  externalResolvers := Resolver.combineDefaultResolvers(resolvers.value.toVector, mavenCentral = false)
  

• You can use Vector directly too.

sbt 1.4.x releases 

sbt 1.4.1 

• Fixes sbt new not echoing back the characters #5954 by @eatkins
• Fixes compiler error reporting in Zinc zinc#931 by @adpi2
• Fixes dependencyBrowseTree etc #5967 by @naderghanbari
• Fixes Scala 2.13-3.0 sandwich support for Scala.JS #5984 by @xuwei-k
• Work around classes directory causing “classes does not exist” error zinc#934 by @eed3si9n
• Adds logging to ClassfileManager output #5990 by @smarter
• Fixes Ctrl-C and Ctrl-D handling #5947/#5975 by @eatkins
• Fixes -Dsbt.color=true not working in some situation #5960 by @eatkins
• Fixes FileAlreadyExistsException when project/target is a symbolic link #5972 by @eatkins
• Fixes ANSI control character appearing in piped output #5966 by @eatkins
• Fixes line reading issue with jEdit #5946 by @eatkins
• Fixes sbt hanging on invalid build.sbt and --batch #5945 by @eatkins
• Fixes .inputrc file support #5973 by @xuwei-k
• Fixes BSP warning diagnostics disappearing on recompilation #5950 by @adpi2
• Fixes BSP support for custom configurations #5930 by @adpi2
• Fixes custom reporter causing MatchError #5948 by @adpi2
• Fixes shellPrompt and release* keys warning on build linting #5983/#5991 by @xirc and @eed3si9n
• Fixes <task>.value macro causing spurious “a pure expression does nothing” warning #5981 by @eed3si9n
• Preserves SemanticDB files in remote cache #5961 by @xuwei-k
• Adds AdoptOpenJDK support for JDK cross building #5964 by @rdesgroppes
• Improves plugins command output by grouping by subproject #5932 by @aaabramov

sbt 1.4.0 

The headline features of sbt 1.4.0 are:

• build server protocol (BSP) support
• sbtn: a native thin client for sbt
• build caching
• ThisBuild / versionScheme to take the guessing out of eviction warning

Build server protocol (BSP) support 

sbt 1.4.0 adds build server protocol (BSP) support, contributed by Scala Center. Main implementation was done by Adrien Piquerez (@adpi2) based on @eed3si9n’s prototype.

When sbt 1.4.0 starts, it will create a file named .bsp/sbt.json containing a machine-readable instruction on how to run sbt -bsp, which is a command line program that uses standard input and output to communicate to sbt server using build server protocol.

How to import to IntelliJ using BSP 

1. Start sbt in a terminal
2. Open IntelliJ IDEA 2020.1.2 or later
3. Select “Open or import”, and select “BSP Project”

How to import to VS Code + Metals 

1. Delete existing .bsp, .metals, .bloop directories if any
2. Open VS Code in the working directory
3. Ignore the prompt to import the project
4. Start sbt -Dsbt.semanticdb=true in the Terminal tab. Wait till it displays “sbt server started”
5. Navigate to Metals view, and select “Restart build server”
6. Type compile into the sbt session to generate SemanticDB files

#5538/#5443 by @adpi2

Native thin client 

sbt 1.4.0 adds an official native thin client called sbtn that supports all tasks. If you’re using the official sbt launcher 1.4.0 and not the knockoff kind you can use --client option to run the native thin client:

$ sbt --client compile
$ sbt --client shutdown

The native thin client will run sbt (server) as a daemon, which avoids the JVM spinup and loading time for the second call onwards. This could be an option if you would like to use sbt from the system shell such as Zsh and Fish.

Remember to call sbt --client shutdown when you’re done! If you want to enable this via an environment variable you can set SBT_NATIVE_CLIENT to true. sbtn binary files are also available from https://github.com/sbt/sbtn-dist/releases/tag/v1.4.0

#5620 by @eatkins

ThisBuild / versionScheme 

sbt 1.4.0 adds a new setting called ThisBuild / versionScheme to track version scheme of the build:

ThisBuild / versionScheme := Some("early-semver")

The supported values are "early-semver", "pvp", and "semver-spec". sbt will include this information into pom.xml and ivy.xml as a property. In addition, sbt 1.4.0 will use the information to take the guessing out of eviction warning when this information is available. #5724 by @eed3si9n

VirtualFile + RemoteCache 

sbt 1.4.0 / Zinc 1.4.0 virtualizes the file paths tracked during incremental compilation. The benefit for this that the state of incremental compilation can shared across different machines, as long as ThisBuild / rootPaths are enumerated beforehand.

To demonstrate this, we’ve also added experimental cached compilation feature to sbt. All you need is the following setting:

ThisBuild / pushRemoteCacheTo := Some(MavenCache("local-cache", file("/tmp/remote-cache")))

Then from machine 1, call pushRemoteCache. This will publish the *.class and Zinc Analysis artifacts to the location. Next, from machine 2, call pullRemoteCache.

zinc#712/#5417 by @eed3si9n

Build linting 

On start up, sbt 1.4.0 checks for unused settings/tasks. Because most settings are on the intermediary to other settings/tasks, they are included into the linting by default. The notable exceptions are settings used exclusively by a command. To opt-out, you can either append it to Global / excludeLintKeys or set the rank to invisible.

#5153 by @eed3si9n

Conditional task 

sbt 1.4.0 adds support for conditional task (or Selective task), which is a new kind of task automatically created when Def.task { ... } consists of an if-expression:

bar := {
  if (number.value < 0) negAction.value
  else if (number.value == 0) zeroAction.value
  else posAction.value
}

Unlike the regular (Applicative) task composition, conditional tasks delays the evaluation of then-clause and else-clause as naturally expected of an if-expression. This is already possible with Def.taskDyn { ... }, but unlike dynamic tasks, conditional task works with inspect command. See Selective functor for sbt for more details. #5558 by @eed3si9n

Incremental build pipelining 

sbt 1.4.0 adds experimental incremental build pipelining. To enable build pipelining for the build:

ThisBuild / usePipelining := true

To opt-out of creating an early output for some of the subprojects:

exportPipelining := false

#5703 by @eed3si9n

sbt-dependency-graph is in-sourced 

sbt 1.4.0 brings in Johannes Rudolph’s sbt-dependency-graph plugin into the code base. Since it injects many tasks per subprojects, the plugin is split into two parts: - MiniDependencyTreePlugin that is enabled by default, bringing in dependencyTree task to Compile and Test configurations - Full strength DependencyTreePlugin that is enabled by putting the following to project/plugins.sbt:

addDependencyTreePlugin

Fixes with compatibility implications 

• Replaces Apache Log4j with our own logger by default to avoid Appender leakage. Use ThisBuild / useLog4J := true to use Log4j. #5731 by @eatkins
• Makes JAR file creation repeatable by sorting entry by name and dropping timestamps #5344/io#279 by @raboof
• Loads bare settings in the alphabetic order of the build files #2697/#5447 by @eed3si9n
• Loads vals from top-to-bottom within a build file #2232/#5448 by @eed3si9n
• HTTP resolvers require explicit opt-in using .withAllowInsecureProtocol(true) #5593 by @eed3si9n
• Ctrl-C during triggered execution ~ returns to the shell instead of shutting down sbt #5804 by @eatkins

Other updates 

• Updates shell to use JLine 3 for better tab completion #5671 by @eatkins
• Adds support for Scala 2.13-3.0 sandwich #5767 by @eed3si9n
• Throws an error if you run sbt from / without -Dsbt.rootdir=true #5112 by @eed3si9n
• Upates StateTransform to accept State => State #5260 by @eatkins
• Fixes various issues around background run #5259 by @eatkins
• Turns off supershell when TERM is set to “dumb” #5278 by @hvesalai
• Avoids using system temporary directories for logging #5289 by @eatkins
• Adds library endpoint for sbt.ForkMain #5315 by @olafurpg
• Avoids using last modified time of directories to invalidate doc #5362 by @eatkins
• Fixes the default artifact of packageSrc for custom configuration #5403 by @eed3si9n
• Fixes task cancellation handling #5446/zinc#742 by @azolotko
• Adds toTaskable method injection to Initialize[A] for tuple syntax #5439 by @dwijnand
• Fixes the error message for an undefined setting #5469 by @nigredo-tori
• Updates semanticdbVersion to 4.3.7 #5481 by @anilkumarmyla
• Adds Tracked.outputChangedW and Tracked.inputChangedW which requires typeclass evidence of JsonWriter[A] instead of JsonFormat[A] #5513 by @bjaglin
• Fixes various supershell interferences #5319 by @eatkins
• Adds extension methods to State to faciliate sbt server communication #5207 by @eed3si9n
• Adds support for weighed tags for testGrouping #5527 by @frosforever
• Updates to sjson-new, which shades Jawn 1.0.0 #5595 by @eed3si9n
• Fixes NullPointerError when credential realm is null #5526 by @3rwww1
• Adds Def.promise for long-running tasks to communicate to another task #5552 by @eed3si9n
• Uses Java’s timestamp on JDK 10+ as opposed to using native call io#274 by @slandelle
• Adds retry with backoff during publish (-Dsbt.repository.publish.attempts set to 3) lm#340 by @izharahmd
• Improves failure message for PUT lm#309 by @swaldman
• Adds provenance to AnalyzedClass zinc#786 by @dwijnand + @mspnf
• Makes hashing childrenOfSealedClass stable zinc#788 by @dwijnand
• Fixes performance regressions around build source monitoring #5530 by @eatkins
• Fixes performance regressions around super shell #5531 by @eatkins
• Various performance improvements in Zinc zinc#756/zinc#763 by @retronym
• Adds a monitor to warn about excessive GC #5812 by @eatkins
• Fixes forked tests running tests twice when they match multiple fingerprints #5800 by @Duhemm

Participation 

sbt 1.4.0 was brought to you by 34 contributors. Ethan Atkins, Eugene Yokota (eed3si9n), Johannes Rudolph, Dale Wijnand, Adrien Piquerez, Jason Zaugg, Arnout Engelen, Josh Soref, Guillaume Martres, Maksim Ochenashko, Anil Kumar Myla, Brice Jaglin, Claudio Bley, João Ferreira, Steve Waldman, frosforever, Alex Zolotko, Heikki Vesalainen, Ismael Juma, Stephane Landelle, Jannik Theiß, izharahmd, lloydmeta, Alexandre Archambault, Eric Peters, Erwan Queffelec, Kenji Yoshida (xuwei-k), Martin Duhem, Olafur Pall Geirsson, Renato Cavalcanti, Vincent PERICART, nigredo-tori. Thanks!

sbt 1.3.x releases 

sbt 1.3.0 

This is the third feature release of sbt 1.x, a binary compatible release focusing on new features. sbt 1.x is released under Semantic Versioning, and the plugins are expected to work throughout the 1.x series.

The headline features of sbt 1.3 are out-of-box Coursier library management, ClassLoader layering, IO improvements, and super shell. Combined together we hope these features will improve the user experience of running your builds.

Changes with compatibility implication 

• Library management with Coursier. See below for details.
• Super shell. See below for details.
• Multi command no longer requires leading semicolon. clean;Test/compile; would work. #4456 by @eatkins
• Deprecates HTTP resolvers, but allow localhost or resolvers marked .withAllowInsecureProtocol(true) #4997
• Deprecates CrossVersion.Disabled. Please use CrossVersion.disabled instead sbt/librarymanagement#316
• ClassLoader management: To prevent resource leaks, sbt 1.3.0 closes the ephemeral ClassLoaders used by the run and test tasks after those tasks complete. This may cause downstream crashes if the task uses ShutdownHooks or if any threads created by the tasks continue running after the task completes. To disable this behavior, either set Compile / run / fork := true or run sbt with -Dsbt.classloader.close=false.

Library management with Coursier 

sbt 1.3.0 adopts Coursier for the library management. Coursier is a dependency resolver like Ivy, rewritten in Scala by Alexandre Archambault (@alexarchambault), aiming to be a faster alternative.

Note: Under some situations, Coursier may not resolve the same way as Ivy (for example remote -SNAPSHOTs are cached for 24 hours). If you wish to go back to Apache Ivy for library management, put the following in your build.sbt:

ThisBuild / useCoursier := false

Many people were involved in the effort of bringing Coursier to sbt. Early in 2018 Leonard Ehrenfried (@leonardehrenfried) started the Coursier-backed LM API implementation as lm#190. During the fall, it was further improved by Andrea Peruffo (@andreaTP), and lm-coursier eventually became part of coursier/sbt-coursier repository maintained by Alex. This spring, Eugene (@eed3si9n) revisited this again to make a few more changes so we can swap out the LM engine in #4614 with the help from Alex.

Turbo mode with ClassLoader layering 

sbt 1.3.0 adds “turbo” mode that enables experimental or advanced features that might require some debugging by the build user when it doesn’t work.

ThisBuild / turbo := true

Initially we are putting the layered ClassLoader (ClassLoaderLayeringStrategy.AllLibraryJars) behind this flag.

sbt has always created two-layer ClassLoaders when evaluating the run and test tasks. The top layer of the ClassLoader contains the scala library jars so that the classes in the scala package may be reused across multiple task evaluations. The second layer loads the rest of the project classpath including the library dependencies and project class files. sbt 1.3.0 introduces experimental classLoaderLayeringStrategy feature that furthers this concept.

Compile / classLoaderLayeringStrategy := ClassLoaderLayeringStrategy.Flat
// default
Compile / classLoaderLayeringStrategy := ClassLoaderLayeringStrategy.ScalaLibrary
// enabled with turbo
Compile / classLoaderLayeringStrategy := ClassLoaderLayeringStrategy.AllLibraryJars

Test / classLoaderLayeringStrategy := ClassLoaderLayeringStrategy.Flat
// default
Test / classLoaderLayeringStrategy := ClassLoaderLayeringStrategy.ScalaLibrary
// enabled with turbo
Test / classLoaderLayeringStrategy := ClassLoaderLayeringStrategy.AllLibraryJars

• ClassLoaderLayeringStrategy.Flat includes all classes and JARs except for the Java runtime. The behavior of tasks using this strategy should be similar to forking without the overhead of starting a new jvm.
• ClassLoaderLayeringStrategy.ScalaLibrary creates a two-layer ClassLoader where Scala standard library is kept warm, similar to sbt 1.2.x
• ClassLoaderLayeringStrategy.AllLibraryJars creates a three-layer ClassLoader where library dependencies, in addition to Scala standard libraries are kept warm

ClassLoaderLayeringStrategy.AllLibraryJars should benefit the response time of run and test tasks. By caching the library jar classloader, the startup latency of the run and test tasks can be reduced significantly when they are run multiple times within the same session. GC pressure is also reduced because libraries jars will not be reloaded every time the task is evaluated.

Note: ClassLoaderLayeringStrategy.AllLibraryJars reuses the singleton object between the tests, which requires libraries to clean after itself.

ClassLoaderLayeringStrategy.Flat on the other hand will benefit certain applications that do not work well with layered ClassLoaders. One such example is Java serialization + serialization proxy pattern used by Scala collections.

ClassLoader layering was contributed by Ethan Atkins (@eatkins) as #4476

IO improvements 

In addition to classloader layering, sbt 1.3.0 incorporates numerous performance enhancements including:

• faster recursive directory listing — sbt internally uses a native library, swoval, that provides a jni interface to native os apis that allow for faster recursive directory listing than the implementations in the java standard library.
• reduced latency of file change detection in continuous builds. In most cases file events will trigger task evaluation within 10ms.

As of this writing sbt 1.3.0’s edit-compile-test loop for 5000 source files is faster than that edit-compile-test with three source files using sbt 0.13, Gradle, and other build tools we tested (see build performance for details). These changes were contributed by Ethan Atkins (@eatkins).

Glob 

sbt 1.3.0 introduces a new type, Glob, that describes a path search query. For example, all of the scala sources in the project directory can be described by Glob(baseDirectory.value, RecursiveGlob / "*.scala") or baseDirectory.value.toGlob / ** / "*.scala", where ** is an alias for RecursiveGlob. Glob expands on PathFinders but they can be composed with no io overhead. Globs can be retrieved using a FileTreeView. For example, one can write:

val scalaSources = baseDirectory.value.toGlob / ** / "*.scala"
val javaSources = baseDirectory.value.toGlob / ** / "*.java"
val allSources = fileTreeView.value.list(Seq(scalaSources, javaSources))

and the FileTreeView will only traverse the base directory once. Globs and FileTreeView were added by Ethan Atkins (@eatkins) in io#178,io#216,io#226

Watch improvements 

sbt 1.3.0 introduces a new file monitoring implementation. It uses enhanced apis for tracking file change events using os events. It adds a new parser that extracts the specific task(s) for which it will monitor source files and rerun when it detects changes. Only source dependencies of the running tasks are monitored. For example, when running ~compile, changes to test source files will not trigger a new build. Between file events, there are also now options to return to the shell, rerun the previous command(s) or exit sbt. These changes were implemented by Ethan Atkins (@eatkins) in io#178,#216,#226,#4512,#4627.

Build definition source watch 

sbt 1.3.0 automatically watches the build definition sources and displays a warning if you execute a task without reloading. This can be configured to reload automatically as follows:

Global / onChangedBuildSource := ReloadOnSourceChanges

This feature was contributed by Ethan Atkins (@eatkins) in #4664

Custom incremental tasks 

sbt 1.3.0 provides support to implement custom incremental tasks based on files. Given a custom task that returns java.nio.file.Path, Seq[java.nio.file.Path], File, or Seq[File], you can define a few helper tasks to make it more incremental.

import java.nio.file._
import scala.sys.process._
val gccCompile = taskKey[Seq[Path]]("compile C code using gcc")
val gccHeaders = taskKey[Seq[Path]]("header files")
val gccInclude = settingKey[Path]("include directory")
val gccLink = taskKey[Path]("link C code using gcc")

gccCompile / sourceDirectory := sourceDirectory.value
gccCompile / fileInputs += (gccCompile / sourceDirectory).value.toGlob / ** / "*.c"
gccInclude := (gccCompile / sourceDirectory).value.toPath / "include"
gccHeaders / fileInputs += gccInclude.value.toGlob / "*.h"
gccCompile / target := baseDirectory.value / "out"

gccCompile := {
  val objectDir = Files.createDirectories((gccCompile / target).value.toPath / "objects")
  def objectFile(path: Path): Path =
    target.value.toPath / path.getFileName.toString.replaceAll(".c$", ".o")
  Files.createDirectories(target.value.toPath)
  val headerChanges = gccHeaders.inputFileChanges.hasChanges
  val changes = gccCompile.inputFileChanges
  changes.deleted.foreach(sf => Files.deleteIfExists(objectFile(sf)))
  val sourceFileChanges = changes.created ++ changes.modified
  val needRecompile = (sourceFileChanges ++ (if (headerChanges) changes.unmodified else Nil)).toSet

  val logger = streams.value.log
  gccCompile.inputFiles.map { sf =>
    val of = objectFile(sf)
    if (!Files.exists(of) || needRecompile(sf)) {
      logger.info(s"Compiling $sf")
      s"gcc -I${gccInclude.value} -c $sf -o $of".!!
    }
    of
  }
}

Given this setup, gccCompile.inputFiles will return a sequence of all of the input c source files, gccCompile.inputFileChanges returns a data structure containing the created, deleted, modified and unmodified files since the last run of gccCompile while gccHeaders.changedInputFiles returns the headers that have changed since the last run of gccCompile. Taken together, these tasks can be used to incrementally only rebuild the source files that need to be rebuilt given the file system changes since the last time gccCompile completed.

In another task such as gccLink, the result of gccCompile can be tracked as well using gccCompile.outputFileChanges.

gccLink := {
  val library = (gccCompile / target).value.toPath / "libmylib.dylib"
  val objectFiles = gccCompile.outputFiles
  val logger = streams.value.log
  if (!Files.exists(library) || gccCompile.outputFileChanges.hasChanges) {
    logger.info(s"Rebuilding $library")
    s"gcc -dynamiclib -o $library ${objectFiles mkString " "}".!!
  }
  library
}

The inputs of a task will automatically be monitored by the ~ command which has a new parser that is context aware. A custom clean task is also implemented for any task that generates file outputs. The clean tasks are aggregated across the project and config scopes. For example, Test / clean will clean all of the files generated by tasks in the Test config declared in the Test config but not the files generated in the Compile config.

This feature was contributed by Ethan Atkins (@eatkins) in #4627.

Super shell 

When running in an ANSI-compatible terminal, sbt 1.3.0 will display the currently running tasks. This gives the developer the idea of what tasks are being processed in parallel, and where the build is spending its time. In homage to Gradle’s “Rich Console” and Buck’s “Super Console”, we call ours “Super shell.”

To opt-out put the following in the build:

ThisBuild / useSuperShell := false

or run sbt with --supershell=false (or -Dsbt.supershell=false). This feature was added by Eugene Yokota (@eed3si9n) as #4396/util#196.

Tracing 

To view the task breakdown visually, run sbt with --traces (or -Dsbt.traces=true). This will generate build.traces file, which is viewable using Chrome Tracing chrome://tracing/. This feature was contributed by Jason Zaugg (@retronym).

To output the task timings on screen, run sbt with --timings (or -Dsbt.task.timings=true -Dsbt.task.timings.on.shutdown=true).

SemanticDB support 

sbt 1.3.0 makes it easier to generate SemanticDB. To enable the generation of SemanticDB build-wide:

ThisBuild / semanticdbEnabled := true
ThisBuild / semanticdbVersion := "4.1.9"
ThisBuild / semanticdbIncludeInJar := false

This was added by @eed3si9n as #4410.

print command 

sbt 1.3.0 adds a new print command, similar to show but prints directly to standard out.

# sbt -no-colors --error  "print akka-cluster/scalaVersion"
2.12.8

This was contributed by David Knapp (@Falmarri) as #4341

Appending Function1 

Function1 can be appended using +=.

Global / onLoad += { s =>
  doSomething()
  s
}

This was contributed by Dale Wijnand (@dwijnand) as #4521.

JDK 11 support 

sbt 1.3.0 is first release of sbt that’s been testing on JDK11 extensively. All integration tests on Travis CI are on AdoptOpenJDK’s JDK 11, which were updated by @eed3si9n as #4389/zinc#639/[zinc640].

• Fixes warnings on JDK 9+ by upgrading to protobuf 3.7.0 zinc#644 by @smarter
• Fixes spurious rebuilds caused by invalidation of rt.jar on JDK 11 #4679 by @eatkins

Other bug fixes and improvements 

• Fixes cross building with a single-letter alias #4355 / #1074 by @eed3si9n
• Removes old warning about global directory #4356 / #1054 by @eed3si9n
• Improves JDK discovery for cross-JDK forking #4313 / #4462 by @raboof
• Expands ~ in -Dsbt.global.base property to user home. #4367 by @kai-chi
• Adds def sequential[A](tasks: Seq[Initialize[Task[A]]]): Initialize[Task[A]]. #4369 by @3tty0n
• Fixes sbt server to send error event on command failure. #4378 by @andreaTP
• Implements cancellation of request by LSP client. #4384 by @andreaTP
• Implements "sbt/completion" command in sbt to server to complete sbt commands. #4397 by @andreaTP
• Fixes errors order reported by sbt server. #4497 by @tdroxler
• Fixes cached resolution. #4424 by @eed3si9n
• The sbt task definition linter warns rather than errors by default. The linter can be disabled entirely by putting import sbt.dsl.LinterLevel.Ignore in scope. #4485 by @eatkins
• Full GC is only automatically triggered when sbt has been idle for at least a minute and is only run at most once between shell commands. This improves shell responsiveness. #4544 by @eatkins
• Avoids NPE in JDK12. #4549 by @retronym
• Fixes the eviction warning summary lm#288 by @bigwheel
• Fixes Zinc’s flag to skip the persistence of API info. zinc#399 by @romanowski
• Fixes Zinc not detecting synthetic top level member changes. #4316/zinc#572 by @jvican
• Zinc to notify callback of generated non-local classes before the compiler’s middle and backend phases. zinc#582 by @jvican
• Removes a use of regex in Zinc for performance. zinc#583 by @retronym
• Fixes incremental compilation involving default arguments. zinc#591 by @jvican
• Adds Analysis callback of Zinc thread-safe. zinc#626 by @dotta
• Fixes a non-zero exit Javadoc not failing the task. zinc#625 by @raboof

Participation 

First, I’d like to introduce Ethan Atkins, a core community member of sbt project, and author of Close Watch that uses native code to provide watch service on macOS. Normally I don’t publicize the number of commits, but here’s the top 10 for sbt 1.3.0:

541 Ethan Atkins
369 Eugene Yokota (eed3si9n)
42  Jorge Vicente Cantero (jvican)
35  Łukasz Wawrzyk
34  Dale Wijnand
24  Andrea Peruffo
16​​  Kenji Yoshida (xuwei-k)
13  Guillaume Martres
7   Arnout Engelen
7   Jason Zaugg

As a community member, Ethan has contributed various IO related improvements to make sbt more responsive in his own time. sbt 1.3.0 reflects many of his ideas.

The last feature release of sbt 1 was sbt 1.2.0 in July, 2018. Since then, we’ve released eight patch releases under sbt 1.2.x for bug fixes, but most of the feature enhancements were merged to develop branch. Over the course of these months, 45 contributors contributors participated in sbt 1.3.0 and Zinc: Ethan Atkins, Eugene Yokota (eed3si9n), Jorge Vicente Cantero (jvican), Łukasz Wawrzyk, Dale Wijnand, Andrea Peruffo, Kenji Yoshida (xuwei-k), Guillaume Martres, Arnout Engelen, Jason Zaugg, Krzysztof Romanowski, Antonio Cunei, Mirco Dotta, OlegYch, Alex Dupre, Nepomuk Seiler, 0lejk4, Alexandre Archambault, Eric Peters, Kazuhiro Sera, Philippus, Som Snytt, Syed Akber Jafri, Thomas Droxler, Veera Venky, bigwheel, Akhtyam Sakaev, Alexey Vakhrenev, Eugene Platonov, Helena Edelson, Ignasi Marimon-Clos, Julien Sirocchi, Justin Kaeser, Kajetan Maliszewski, Leonard Ehrenfried, Mikołaj Jakubowski, Nafer Sanabria, Stefan Wachter, Yasuhiro Tatsuno, Yusuke Izawa, falmarri, ilya, kai-chi, tanishiking, Ólafur Páll Geirsson. Thank you!

sbt 1.2.x releases 

sbt 1.2.1 

Forward bincompat breakage 

If you are writing a plugin, please use 1.2.1+, and avoid 1.2.0.

We unintentionally broke forward binary compatibility in 1.2.0. If someone publishes an sbt plugin using sbt 1.2.0, it cannot be used from sbt 1.0.x or 1.1.x. sbt 1.2.1 reverts the change, so the forward compatibility is restored. Unfortunately, this means we won’t be able to use varargs in inThisBuild(...) etc again.

Note that we might eventually break forward compatibility, like we did in 0.13.5 for AutoPlugin, but only when the tradeoff is worth it.

The project Foo references an unknown configuration “bar“ 

Second regression fix is for the wall of warnings you might have seen in 1.2.0 that looks as follows:

[warn] The project ProjectRef(uri("file:/Users/xxx/work/akka/"), "akka-actor-typed") references an unknown configuration "multi-jvm" and was guessed to be "Multi-jvm".
[warn] This configuration should be explicitly added to the project.
[warn] The project ProjectRef(uri("file:/Users/xxx/work/akka/"), "akka-actor-typed-tests") references an unknown configuration "multi-jvm" and was guessed to be "Multi-jvm".
[warn] This configuration should be explicitly added to the project.

The original issue was that unified slash syntax doesn’t pick the configuration names when the configuration is not part of the subproject. Since this warning is immaterial, we are removing them in this patch release.

One thing the plugin authors can start doing is declaring the custom configuration as hidden, and adding them into the subprojects as follows:

import sbt._
import sbt.Keys._

object ParadoxPlugin extends AutoPlugin {
  val ParadoxTheme = config("paradox-theme").hide
  override def projectConfigurations: Seq[Configuration] = Seq(ParadoxTheme)

  ....
}

We are also looking into improving unified slash syntax parser to make it more robust.

Other bug fixes 

• Updates IO.relativize for JDK 9. io#175 by @eatkins
• Fixes logic for adding external class file manager. zinc#562 by @allanrenucci

Contributors 

A huge thank you to everyone who’s helped improve sbt and Zinc 1 by using them, reporting bugs, improving our documentation, porting builds, porting plugins, and submitting and reviewing pull requests.

sbt 1.2.1 was brought to you by 4 contributors, according to git shortlog -sn --no-merges v1.2.1...v1.2.0 on sbt, zinc, librarymanagement, util, io, launcher-package, and website: Eugene Yokota, Aaron S. Hawley, Ethan Atkins, and Allan Renucci. Thanks! Also special thanks to Ches Martin and Yoshida-san for reporting these issues.

sbt 1.2.0 

Warning: We found forward compatibility breakage in 1.2.0, so we recommend everyone to upgrade to sbt 1.2.1 or later.

The headline features of sbt 1.2 are cross JDK forking, composite project, and experimental thin clients. But, there are lots of other bug fixes and enhancements that we’ve been accumulating for six months since sbt 1.1.

SbtPlugin for plugin development 

SbtPlugin is a plugin to declare a project for sbt plugins. This automatically brings in scripted tests, and sets sbtPlugin := true.

lazy val root = (project in file("."))
  .enablePlugins(SbtPlugin)

Compatibility note: ScriptedPlugin is no longer a triggered plugin.

#3875 by @eed3si9n

Cross JDK forking 

For forked run and test, java++ can now switch Java Home.

sbt:helloworld> run
[info] Running (fork) Hello
[info] 1.8.0_171
sbt:helloworld> java++ 10!
[info] Reapplying settings...
sbt:helloworld> run
[info] Running (fork) Hello
[info] 10.0.1

sbt will try to detect Java homes into discoveredJavaHomes setting, supporting shyiko/jabba. This can be augmented by Global / javaHomes:

Global / javaHomes += "6" -> file("/something/java-6")

This feature is intended for testing your library in an older JVM to check compatibility.

#4139 by @2m, @cunei, and @eed3si9n

scalaVersion-filtered aggregation 

In 2015 James Roper contributed scalaVersion-filtered aggregation to sbt-doge. This feature is brought back into sbt 1.2 by Rui Gonçalves (@ruippeixotog) in #3698/#3995!

This extends switch command ++ to take an optional <command>:

> ++2.12.7 compile

This will aggregate only the subproject where ++2.12.7 is valid, which is useful when you have a build where some subprojects are 2.11 only etc.

Composite project 

sbt 1.2.0 introduces “composite project” trait, which allows plugin authors to generate subprojects, for example for cross building.

trait CompositeProject {
  def componentProjects: Seq[Project]
}

This was contributed by @BennyHill as #4056.

Project matrix 

Experimental. As a reference implementation of the CompositeProject I implemented a new DSL called projectMatrix introduced by sbt-projectmatrix plugin.

lazy val core = (projectMatrix in file("core"))
  .scalaVersions("2.12.7", "2.11.12")
  .settings(
    name := "core"
  )
  .jvmPlatform()

lazy val app = (projectMatrix in file("app"))
  .dependsOn(core)
  .scalaVersions("2.12.7")
  .settings(
    name := "app"
  )
  .jvmPlatform()

The aim of the plugin is to support a generic notion of cross building (Scala version, platform, etc) expressed using subprojects. In the above projectMarix will produce three subprojects: coreJVM2_12, coreJVM2_11, and appJVM2_12.

Semantic Version selector API 

sbt 1.2.0 introduces Semantic Version selector on VersionNumber() datatype supporting basic match, comparison (<=, <, >=, >), combination (>1.0.0 <2.0.0, ||), ranges (A.B.C - D.E.F), and wildcard (2.12.x).

scala> import sbt.librarymanagement.{ VersionNumber, SemanticSelector }
import sbt.librarymanagement.{VersionNumber, SemanticSelector}

scala> VersionNumber("2.12.5").matchesSemVer(SemanticSelector(">=2.12"))
res1: Boolean = true

scala> VersionNumber("2.12.5").matchesSemVer(SemanticSelector("<2.12"))
res2: Boolean = false

scala> VersionNumber("2.13.0-M4").matchesSemVer(SemanticSelector("2.13"))
res3: Boolean = false

scala> VersionNumber("2.12.5").matchesSemVer(SemanticSelector("2.12.1 - 2.12.7"))
res4: Boolean = true

scala> VersionNumber("2.12.5").matchesSemVer(SemanticSelector("2.12.x"))
res5: Boolean = true

scala> VersionNumber("2.12.5").matchesSemVer(SemanticSelector("2.11.x || 2.12.x"))
res6: Boolean = true

Note: This has no effect on library management at the moment.

This was contributed by Rikito Taniguchi (@tanishiking) as lm#239.

addPluginSbtFile command 

There’s been a request from IntelliJ to safely inject a plugin to a build. sbt 1.2.0 adds -addPluginSbtFile command to do so.

$ cat /tmp/extra.sbt
addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.14.7")

$ sbt -addPluginSbtFile=/tmp/extra.sbt
...
sbt:helloworld> plugins
In file:/xxxx/hellotest/
  ...
  sbtassembly.AssemblyPlugin: enabled in root

Implmented by @eed3si9n as #4211.

Extensible sbt server 

Experimental. sbt server can now be extended via the plugin.

    Global / serverHandlers += ServerHandler({ callback =>
      import callback._
      import sjsonnew.BasicJsonProtocol._
      import sbt.internal.protocol.JsonRpcRequestMessage
      ServerIntent(
        {
          case r: JsonRpcRequestMessage if r.method == "lunar/helo" =>
            jsonRpcNotify("lunar/oleh", "")
            ()
        },
        PartialFunction.empty
      )

This feature is still experimental and the API may change in the future.

#3975 by @eed3si9n

Thin client(s) 

Experimental. sbt 1.2.0 adds a new mode called -client. When sbt is started with -client command, it no longer to loads the build, and instead tries to connect to an instance of sbt server over JSON-RPC. When the server is not running (portfile is not found), it will fork a new instance of sbt entirely in a new JVM.

This lets you invoke sbt from the terminal shell or from an editor.

$ time sbt -client clean
[info] entering *experimental* thin client - BEEP WHIRR
[info] server was not detected. starting an instance
[info] waiting for the server...
[info] waiting for the server...
[info] waiting for the server...
[info] waiting for the server...
[info] server found
> clean
[success] completed
sbt -client clean  9.23s user 2.33s system 22% cpu 50.558 total

# server stays
$ ps | rg java
21860 ttys015    1:22.43 java -Xms2048M -Xmx2048M -Xss2M -jar /usr/local/Cellar/sbt/1.1.6/libexec/bin/sbt-launch.jar
22014 ttys015    0:00.00 rg java

$ time sbt -client clean
[info] entering *experimental* thin client - BEEP WHIRR
> clean
[info] Updating ...
[info] Done updating.
[success] completed
sbt -client clean  3.39s user 1.75s system 104% cpu 4.898 total

To end the server, call sbt -client shutdown. #4227 by @eed3si9n

In addition, there are also an alternative thin clients cb372/sbt-client and dwijnand/sbtl implemented using Rust.

Changes with compatibility implication 

• Removes deprecated commands -, --, and ---. Use onFailure, sbtClearOnFailure, and resumeFromFailure instead. #4124
• Makes ++ fail when it doesn’t affect any subprojects #4269 by @eed3si9n

Other bug fixes and improvements 

• Fixes output caching bug. util#169 by @bpholt
• Fixes “destination file exists” error message. lm#255 by @eed3si9n
• Reintroduces Command.process(String, State): State. #4023 by @dwijnand
• Fixes active.json not getting removed on JVM shutdown. #4194 by @veera83372
• Fixes file permission error (”CreateFile() failed”) while reading the timestamp on Windows. io#134 by @cunei
• Fixes the linter that detects missing .value. #4090 by @eed3si9n
• Fixes StringIndexOutOfBoundsException in removeEscapeSequences. util#139 by @dwijnand
• Fixes OkHttp’s JavaNetAuthenticator with a null check. lm#177 by @eed3si9n
• Fixes Sonatype timeout issue by extending the default timeout to 1h. lm#246 by @peterneyens
• Fixes thread thrashing error during the parallel download. lm249 by @OlegYch
• Fixes JavaDoc warnings logged as errors. zinc#506 by @kaygorodov
• Fixes class dependency not picking up classOf[A]. zinc#510 by @natansil
• Fixes class dependency including non-existing objects. zinc422 by @romanowski
• Fixes link to the documentation of deprecated 0.10/0.12 DSL syntax. #3901 by [@colindean]
• Fixes the documentation of skip key. #3926 by @dkim
• Fixes race condition in non-forked parallel tests. #3985 by @retronym
• Fixes Ctrl-C handing in forked tests when Global / cancelable is set to true. #4226 by @driquelme
• Fixes the stacktrace of run. #4232 by @eed3si9n
• Bumps the version of Giter8 used by sbt new to 0.11.0, fixing various issues #4263 by @eed3si9n
• Improves Javac error parsing. zinc#557 by @eed3si9n
• Displays only the eviction warning summary by default, and make it configurable using ThisBuild / evictionWarningOptions. lm211 and #3947 by @exoego
• Allow varargs in inThisBuild(...), inConfig(C)(...), inTask(t)(...), inScope(scope)(...). #4106 by @dwijnand
• Adds fgRun and fgRunMain tasks that behaves like sbt 0.13’s run. #4216 by @agaro1121
• Supports test.script and pending.script as the scripted file name. #4220 by @regadas
• Supports aliases in inspect command. #4221 by @gpoirier
• Adds the current project’s id to ~’s watching message. #2038 / #3813 by @dwijnand
• Changes PathFinder#get to get(). io#104 by @dwijnand
• Improves the error message when access is denied. lm#203 by @stephennancekivell
• Improve the warning message “Choosing local” to something more actionable. lm#248 by @khvatov
• Adds an option to ignore scalac options change. zinc#548 by @lukaszwawrzyk
• Enable parallel execution of scripted in the plugin. #3891 by @jvican
• Adds factory methods for Configuration axis scope filters inConfigurationsByKeys and inConfigurationsByRefs. #3994
• Adds lastGrep, loadFailed, etc commands to replace the kebab-cased commands. #4080 by @naferx, #4159 by @Asamsig, and #4169 by @tiqwab
• Adds timestamp field to JUnitXML report. 4154 by @timcharper
• “Loading settings” log messages now show subproject name. #4164 by @alodavi
• about command sorts and indents plugins list. #4187 by @mcanlas
• -Dsbt.offline sets offline setting. #4198 by @eed3si9n
• Selects most recent JDK during cross JDK forking (see below for details) #4245 by @raboof

Internal 

• Removes some compiler warnings. #3087 by @dwijnand
• Lots of other refactorings by @dwijnand
• Removes some compiler warnings in Zinc. zinc#493 by @exoego
• Perf: Prevents creation of useless URI copies in IO.directoryURI. io#132 by @jrudolph
• Perf: Avoids reflect universe initialization in initStringCodecs. util#153 by @jrudolph
• Perf: Speeds up Parsers.validID. #3952 by @jrudolph
• Perf: Optimizes scope delegation by hand rolling for comprehension. #4003 by @jrudolph and @eed3si9n
• Use val instead of var in an internal code. #4253 by @xuwei-k

Contributors 

Thanks again to everyone who’s helped improve sbt and Zinc 1.

sbt 1.2.0 was brought to you by 60 contributors. Dale Wijnand, Eugene Yokota, Kenji Yoshida (xuwei-k), Yasuhiro Tatsuno (exoego), Łukasz Wawrzyk, Jorge Vicente Cantero (jvican), Alistair Johnson, Antonio Cunei, Jason Zaugg, Rikito Taniguchi (tanishiking), Seiya Mizuno, Tim Harper, Aloisia Davì (alodavi), Arnout Engelen, Ethan Atkins, Johannes Rudolph, Krzysztof Romanowski, Allan Renucci, Brian P. Holt, Filipe Regadas, Hiroshi Ito, Martijn Hoekstra, OlegYch, Seth Tisue, natans, Aaron S. Hawley, Alex Khvatov, Alexander Samsig, Andreas Jim-Hartmann, Andrei Pozolotin, Andrey Kaygorodov, Anthony Garo, Christopher Hunt, Colin Dean, Daniel Riquelme, Deokhwan Kim, Gerard Maas, Guillaume Poirier, Heikki Vesalainen, Jason Pickens, Jonas Fonseca, Julien Jerphanion, Justin Pihony, Kazufumi Nishida, Kyle Goodale, Maksym Fedorov, Mark Canlas, Martynas Mickevičius, Michael Pollmeier, Mike Skells, Nafer Sanabria, Naohisa Murakami (tiqwab), PanAeon, Peter Neyens, Rui Gonçalves, Sean Sullivan, Stephen Nancekivell, Veera Venky, blakkan, ortigali. Thank you!

sbt 1.1.x releases 

sbt 1.1.6 

Bug fixes 

• Fixes file watching for Unix/Linux. io#150 by @eatkins
• Fixes packageBin not creating file when deleted. sbt/sbt#4161 by @dadarakt
• Fixes help -v rendering of multi-line descriptions. #4160 by @ninjalama
• Fixes —error etc to set log level. #4162 by @holdenk
• Handles managedSources writing into unmanaged source directories. #4099 by @eatkins
• Fixes handling of overflows in EventMonitor. io#155 by @eatkins
• Recovers “Resolving…” log under UpdateLogging.Full. lm#240 by @hodga
• Fixes -Dconfig.resource=/path/to/configFile conflicting with Gigahorse. lm#241 by @tanishiking
• Removes use of deprecated ModifiedTime methods. io#154 by @dwestheide
• Fixes tests on Windows. io#153 by @OlegYch

Contributors 

A huge thank you to everyone who’s helped improve sbt and Zinc 1 by using them, reporting bugs, improving our documentation, porting builds, porting plugins, and submitting and reviewing pull requests.

sbt 1.1.6 was brought to you by 15 contributors, according to git shortlog -sn --no-merges v1.1.5...v1.1.6 on sbt, zinc, librarymanagement, util, io, launcher-package, and website: Ethan Atkins, Eugene Yokota, Dale Wijnand, Aaron S. Hawley, OlegYch, Richard Summerhayes, Jannis (dadarakt), Rikito Taniguchi (tanishiking), Øyvind Høisæther, Daniel Westheide, Harrison Houghton, Holden Karau, Håkon Wold, Jason Zaugg, and tekay.

sbt 1.1.5 

Bug fixes 

• Fixes the latency between file modification events and triggered execution. io#142 and sbt#4096 by @eatkins
• Fixes NPE that could arise from WatchEvent io#140 by @oneill
• Fixes deleted files not triggering ~. sbt#4098 by @eatkins
• Fixes MacOSXWatchService to meet the WatchService API. io#142 by @eatkins
• Avoids printing RejectedExectionExeption stack trace after cancellation. sbt#4058 by @retronym
• Fixes Java version checking on Windows. lp#227 / lp#228 by @jessicah and @spangaer
• Fixes unexpected responses from sbt server. sbt#4093 by @laughedelic
• Re-fix console and JLine bug. sbt#4123 by @eed3si9n
• Fixes grammar for contributors guide. sbt#4133 by @som-snytt

Improvements 

• Performance optimization for Zinc. zinc#492 by @retronym
• Adds support for detecting Dotty compiler plugins. zinc#529 by @liufengyun
• Bumps Scala to 2.12.6. sbt#4129 by @SethTisue
• Updates to JLine 2.14.6. sbt#4087 by @hvesalai
• Start sbt in VS Code terminal window. See below.

Watcher improvements 

Continuing from sbt 1.1.4, Ethan Atkins contributed fixes and improvements for triggered execution ~ watcher. sbt 1.1.5 should fix the latency between file modification events and the command execution.

VS Code extension update 

We released a new sbt VS Code extension that starts sbt session in the embedded terminal window. This was contributed by Robert Walker (@WalkingOlof) in sbt#4130.

sbt by example 

We added sbt by example to the sbt documentation. This is a single-page guide that takes you from zero to building an app on Docker, inspired by, and largely based on William Narmontas (@ScalaWilliam)’s Essential sbt.

Contributors 

A huge thank you to everyone who’s helped improve sbt and Zinc 1 by using them, reporting bugs, improving our documentation, porting builds, porting plugins, and submitting and reviewing pull requests.

sbt 1.1.5 was brought to you by 21 contributors, according to git shortlog -sn --no-merges v1.1.4...v1.1.5 on sbt, zinc, librarymanagement, util, io, launcher-package, and website: Eugene Yokota, Ethan Atkins, Jason Zaugg, Liu Fengyun, Antonio Cunei, Dale Wijnand, Roberto Bonvallet, Alexey Alekhin, Daniel Parks, Heikki Vesalainen, Jean-Luc Deprez, Jessica Hamilton, Kenji Yoshida (xuwei-k), Nikita Gazarov, OlegYch, Richard Summerhayes, Robert Walker, Seth Tisue, Som Snytt, oneill, and 杨博 (Yang Bo)

sbt 1.1.4 

Bug fixes 

• Fixes triggered execution on macOS. See below for details.
• Fixes running console twice messing up JLine. #3482/#4054 by @eed3si9n
• Fixes updateSbtClassifiers. #4070/#3432 by @steinybot
• Fixes Java error message handling. zinc#524/zinc#525 by @retronym and @dwijnand
• Fixes the error message linking to the migration guide. #4063 by @dwijnand
• Fixes batch script so sbt runs on JDK 10 on Windows. lp#225 by @eed3si9n
• Fixes bash script so sbt -debug changes log level to debug. lp#226 by @eed3si9n

Improvements 

• Exposes sbt.io.JavaMilli. io#139 by @dwijnand
• Adds -Dsbt.launcher.cp.prepend JVM flag that is used for monkey patching sbt. launcher#50 by @fommil

Triggered execution on macOS 

sbt has long had issues with triggered execution on macOS. Ethan Atkins has contributed a fix for this problem by merging MacOSXWatchService from his CloseWatch. Thanks, Ethan!

Credit also goes to Greg Methvin and Takari’s directory-watcher. #3860/#4071/io#138 by @eatkins

Running sbt with standby 

One of the tricky things you come across while profiling is figuring out the process ID, while wanting to profile the beginning of the application.

For this purpose, we’ve added sbt.launcher.standby JVM flag. Starting sbt 1.1.4, you can run:

$ sbt -J-Dsbt.launcher.standby=20s exit

This will count down for 20s before doing anything else. launcher#51 by @eed3si9n

Loading performance improvement 

Using Flame graph (if you haven’t yet, check out Profiling JVM applications post), Jason Zaugg identified hashing code of the build file to be one of the hot paths during sbt startup. Flame graph supports Ctrl+F to filter on method names; and when I ran it, it showed 4.5% of the time was spent in Eval#evalCommon method.

Instead of creating an intermediate Array[Byte] and passing it to MessageDigest at the end, Jason suggested that we pass the arrays to MessageDigest#update in a more procedural style. After confirming that it worked, we’ve next identified file timestamp code to be the next bottle neck using Flame graph, so that was switched to using NIO. After both changes, Eval#evalCommon’s footprint reduced to 2.3%.

This means that your build loads slightly faster on sbt 1.1.4 (about 0.54s faster on akka/akka, for example). #4067 by @eed3si9n

Contributors 

A huge thank you to everyone who’s helped improve sbt and Zinc 1 by using them, reporting bugs, improving our documentation, porting builds, porting plugins, and submitting and reviewing pull requests.

sbt 1.1.4 was brought to you by 11 contributors, according to git shortlog -sn --no-merges v1.1.2...v1.1.4 on sbt, zinc, librarymanagement, util, io, launcher-package, and website: Eugene Yokota, Dale Wijnand, 杨博 (Yang Bo), Ethan Atkins, Sam Halliday, Aaron S. Hawley, Gabriele Petronella, Jason Steenstra-Pickens, Jason Zaugg, Julien Jean Paul Sirocchi, and aumann.

sbt 1.1.2 

Bug fixes 

• Fixes triggered execution’s resource leak by caching the watch service. #3999 by @eatkins
• Fixes classloader inheriting the dependencies of Scala compiler during run zinc#505 by @eed3si9n
• Fixes forked test concurrency issue. #4030 by @eatkins
• Fixes new command leaving behind target directory #4033 by @eed3si9n
• Fixes handling on null Content-Type. lm214 by @staale
• Fixes null handling of managedChecksums in ivySettings file. lm#218 by @IanGabes
• Adds sbt.boot.lock as a JVM property to opt-out of locking. #3927 by @dwijnand
• Provides SBT_GLOBAL_SERVER_DIR env var as a workaround to long socket file path on UNIX. #3932 by @dwijnand
• Fixes forked runs reporting noisy “Stream closed” exception. #3970 by @retronym
• Fixes test compilation not getting included in VS Code save trigger. #4022 by @tmiyamon
• Fixes sbt server responding with string id when number id passed. #4025 by @tiqwab
• Fixes getDecoder in Analysis format zinc#502 by @jilen
• Fixes equal / hashCode inconsistencies around Array. zinc#513 by @eed3si9n
• Whitelists java9-rt-ext-output in rt export process lp#211 by @eatkins
• Fixes JDK version detection for Java 10 friendliness. lp#219 by @eed3si9n and @2m
• Fixes quoting in Windows bat file. lp#220 by @ForNeVeR
• Fixes -error not suppressing startup logs. #4036 by @eed3si9n

Improvements 

• Performance optimization around logging. util#152 by @retronym
• Performance fix by caching the hashCode of Configuration. lm#213 by @retronym
• Returns error code -33000L on sbt server when a command fails. #3991 by @dwijnand
• Allows wildcards in organization and artifact. #215 by @dhs3000
• Updates to latest Jsch to support stronger key exchange algorithms. lm#217 by @ryandbair
• Fixes preloading of compiler bridge. lp#222 by @analytically

Internal 

• Updates contribution guide. #3960/#4019 by @eed3si9n and @itohiro73
• Deletes buildinfo.BuildInfo from sbt main that was intended for testing. 3967 by @dwijnand and @xuwei-k
• Various improvements around Zinc benchmark by @retronym

Contributors 

sbt 1.1.2 was brought to you by 23 contributors, according to git shortlog -sn --no-merges v1.1.1...v1.1.2 on sbt, zinc, librarymanagement, util, io, launcher-package, and website: Dale Wijnand, Eugene Yokota, Jason Zaugg, Kenji Yoshida (xuwei-k), Ethan Atkins, Martijn Hoekstra, Martynas Mickevičius, Dennis Hörsch, Hosam Aly, Antonio Cunei, Friedrich von Never, Hiroshi Ito, Ian Gabes, Jilen Zhang, Mathias Bogaert, Naohisa Murakami (tiqwab), Philippus Baalman, Ryan Bair, Seth Tisue, Ståle Undheim, Takuya Miyamoto (tmiyamon), Yasuhiro Tatsuno. Thank you!

sbt 1.1.1 

Bug fixes 

• Fixes “Modified names for (class) is empty” error. zinc#292 / zinc#484 by @jvican (Scala Center)
• Fixes tab completion in console while running in batch mode as sbt console. #3841/#3876 by @eed3si9n
• Fixes file timestamp retrieval of missing files on Windows. #3871 / io#120 by @cunei
• Aligns the errors thrown by file timestamp implementations. Fixes #3894 / io#121 by @j-keck
• Adds file timestamps native support for FreeBSD. #3894 / io#124 by @cunei
• Fixes JDK 10 version string parsing. sbt/sbt-launcher-package#209 by @2m

Improvements 

• Deprecates Extracted#append in favour of appendWithSession or appendWithoutSession. #3865 by @dwijnand
• Adds a new global Boolean setting called autoStartServer. See below.
• Upgrades Scala versions used for sbt cross building ^^. #3923 by @dwijnand
• Many documentation maintenance changes by @xuwei-k.

autoStartServer setting 

sbt 1.1.1 adds a new global Boolean setting called autoStartServer, which is set to true by default. When set to true, sbt shell will automatically start sbt server. Otherwise, it will not start the server until startSever command is issued. This could be used to opt out of server for security reasons.

#3922 by @swaldman

Contributors 

sbt 1.1.1 was brought to you by 16 contributors, according to git shortlog -sn --no-merges v1.1.0 ..v1.1.0 on sbt, zinc, librarymanagement, util, io, and website: Kenji Yoshida (xuwei-k), Eugene Yokota, Dale Wijnand, Antonio Cunei, Steve Waldman, Arnout Engelen, Deokhwan Kim, OlegYch, Robert Walker, Jorge Vicente Cantero (jvican), Claudio Bley, Eric Peters, Lena Brüder, Seiya Mizuno, Seth Tisue, j-keck. Thank you!

sbt 1.1.0 

This is a feature release for sbt 1.0.x series.

Features, fixes, changes with compatibility implications 

• sbt server feature is reworked in sbt 1.1.0. See below.
• Changes version setting default to 0.1.0-SNAPSHOT for compatibility with Semantic Versioning. #3577 by @laughedelic

Features 

• Unifies sbt shell and build.sbt syntax. See below.

Fixes 

• Fixes ClasspathFilter that was causing Class.forName to not work in run. zinc#473 / #3736 / #3733 / #3647 / #3608 by @ravwojdyla
• Fixes Java compilation causing NullPointerException by making PositionImpl thread-safe. zinc#465 by @eed3si9n
• Fixes PollingWatchService by preventing concurrent modification of keysWithEvents map. io#90 by @mechkg, which fixes ~ related issues #3687, #3695, and #3775.
• Provides workaround for File#lastModified() losing millisecond-precision by using native code when possible. io#92/io#106 by @cunei
• Fixes IO.relativize not working with relative path. io#108 by @dwijnand
• Fixes warning message when multiple instances are detected. #3828 by @eed3si9n
• Fixes over-compilation bug with Java 9. zinc#450 by @retronym
• Fixes handling of deeply nested Java classes. zinc#423 by @romanowski
• Fixes JavaDoc not printing all errors. zinc#415 by @raboof
• Preserves JAR order in ScalaInstance.otherJars. zinc#411 by @dwijnand
• Fixes used name when it contains NL. zinc#449 by @jilen
• Fixes handling of ThisProject. #3609 by @dwijnand
• Escapes imports from sbt files, so if user creates a backquoted definition then task evaluation will not fail. #3635 by @panaeon
• Removes reference to version 0.14.0 from a warning message. #3693 by @saniyatech
• Fixes screpl throwing “Not a valid key: console-quick”. #3762 by @xuwei-k
• Restores Scala 2.13.0-M1 support. #461 by @dwijnand
• Fixes the encoding of Unix-like file path to use file:///. #3805 by @eed3si9n
• Fixes Log4J2 initialization error during startup. #3814 by @dwijnand

Improvements 

• Filters scripted tests based on optional project/build.properties. See below.
• Adds Project#withId to change a project’s id. #3601 by @dwijnand
• Adds reboot dev command, which deletes the current artifact from the boot directory. This is useful when working with development versions of sbt. #3659 by @eed3si9n
• Adds a check for a change in sbt version before reload. #1055/#3673 by @RomanIakovlev
• Adds a new setting insideCI, which indicates that sbt is likely running in an Continuous Integration environment. #3672 by @RomanIakovlev
• Adds nameOption to Command trait. #3671 by @miklos-martin
• Adds POSIX permission operations in IO, such as IO.chmod(..). io#76 by @eed3si9n
• Treat sbt 1 modules using Semantic Versioning in the eviction warning. lm#188 by @eed3si9n
• Uses kind-projector in the code. #3650 by @dwijnand
• Make displayOnly etc methods strict in Completions. #3763 by @xuwei-k

Unified slash syntax for sbt shell and build.sbt 

This adds unified slash syntax for both sbt shell and the build.sbt DSL. Instead of the current <project-id>/config:intask::key, this adds <project-id>/<config-ident>/intask/key where <config-ident> is the Scala identifier notation for the configurations like Compile and Test. (The old shell syntax will continue to function)

These examples work both from the shell and in build.sbt.

Global / cancelable
ThisBuild / scalaVersion
Test / test
root / Compile / compile / scalacOptions
ProjectRef(uri("file:/xxx/helloworld/"),"root")/Compile/scalacOptions
Zero / Zero / name

The inspect command now outputs something that can be copy-pasted:

> inspect compile
[info] Task: sbt.inc.Analysis
[info] Description:
[info]  Compiles sources.
[info] Provided by:
[info]  ProjectRef(uri("file:/xxx/helloworld/"),"root")/Compile/compile
[info] Defined at:
[info]  (sbt.Defaults) Defaults.scala:326
[info] Dependencies:
[info]  Compile/manipulateBytecode
[info]  Compile/incCompileSetup
....

#1812/#3434/#3617/#3620 by @eed3si9n and @dwijnand

sbt server 

sbt server feature was reworked to use Language Server Protocol 3.0 (LSP) as the wire protocol, a protocol created by Microsoft for Visual Studio Code.

To discover a running server, sbt 1.1.0 creates a port file at ./project/target/active.json relative to a build:

{"uri":"local:///Users/foo/.sbt/1.0/server/0845deda85cb41abcdef/sock"}

local: indicates a UNIX domain socket. Here’s how we can say hello to the server using nc. (^M can be sent Ctrl-V then Return):

$ nc -U /Users/foo/.sbt/1.0/server/0845deda85cb41abcdef/sock
Content-Length: 99^M
^M
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "initializationOptions": { } } }^M

sbt server adds network access to sbt’s shell command so, in addition to accepting input from the terminal, server also to accepts input from the network. Here’s how we can call compile:

Content-Length: 93^M
^M
{ "jsonrpc": "2.0", "id": 2, "method": "sbt/exec", "params": { "commandLine": "compile" } }^M

The running sbt session should now queue compile, and return back with compiler warnings and errors, if any:

Content-Length: 296
Content-Type: application/vscode-jsonrpc; charset=utf-8

{"jsonrpc":"2.0","method":"textDocument/publishDiagnostics","params":{"uri":"file:/Users/foo/work/hellotest/Hello.scala","diagnostics":[{"range":{"start":{"line":2,"character":26},"end":{"line":2,"character":27}},"severity":1,"source":"sbt","message":"object X is not a member of package foo"}]}}

#3524/#3556 by @eed3si9n

VS Code extension 

The primary use case we have in mind for the sbt server is tooling integration such as editors and IDEs. As a proof of concept, we created a Visual Studio Code extension called Scala (sbt).

Currently this extension is able to:

• Run compile at the root project when *.scala files are saved. #3524 by @eed3si9n
• Display compiler errors.
• Display log messages. #3740 by @laughedelic
• Jump to class definitions. #3660 by @wpopielarski

Filtering scripted tests using project/build.properties 

For all scripted tests in which project/build.properties exist, the value of the sbt.version property is read. If its binary version is different from sbtBinaryVersion in pluginCrossBuild the test will be skipped and a message indicating this will be logged.

This allows you to define scripted tests that track the minimum supported sbt versions, e.g. 0.13.9 and 1.0.0-RC2. #3564/#3566 by @jonas

Contributors 

sbt 1.1.0 was brought to you by 33 contributors, according to git shortlog -sn --no-merges v1.0.4..v1.1.0 on sbt, zinc, librarymanagement, util, io, and website: Eugene Yokota, Dale Wijnand, Antonio Cunei, Kenji Yoshida (xuwei-k), Alexey Alekhin, Simon Schäfer, Jorge Vicente Cantero (jvican), Miklos Martin, Jeffrey Olchovy, Jonas Fonseca, Andrey Artemov, Arnout Engelen, Dominik Winter, Krzysztof Romanowski, Roman Iakovlev, Wiesław Popielarski, Age Mooij, Allan Timothy Leong, Ivan Poliakov, Jason Zaugg, Jilen Zhang, Long Jinwei, Martin Duhem, Michael Stringer, Michael Wizner, Nud Teeraworamongkol, OlegYch, PanAeon, Philippus Baalman, Pierre Dal-Pra, Rafal Wojdyla, Saniya Tech, Tom Walford, and many others who contributed ideas. Thank you!

sbt 1.0.x releases 

sbt 1.0.4 

This is a hotfix release for sbt 1.0.x series.

Bug fixes 

• Fixes undercompilation of value classes when the underlying type changes. zinc#444 by @smarter
• Fixes ArrayIndexOutOfBoundsException on Ivy when running on Java 9. ivy#27 by @xuwei-k
• Fixes Java 9 warning by upgrading to launcher 1.0.2. ivy#26/launcher#45 by @dwijnand
• Fixes -jvm-debug on Java 9. launcher-package197 by @mkurz
• Fixes run outputting debug level logs. #3655/#3717 by @cunei
• Fixes performance regression caused by classpath hashing. zinc#452 by @jvican, @fommil provided reproduction, and @eed3si9n fixed https://github.com/sbt/zinc/issues/457
• Fixes performance regression of testQuick. #3680/#3720 by @OlegYch
• Disables Ivy log4j caller location calculation for performance regression reported in #3711. util#132 by @leonardehrenfried
• Works around Scala compiler’s templateStats() not being thread-safe. #3743 by @cunei
• Fixes “Attempting to overwrite” error message. lm#174 by @dwijnand
• Fixes incorrect eviction warning message. lm#179 by @xuwei-k
• Registers Ivy protocol only for http: and https: to be more plugin friendly. lm183 by @tpunder
• Fixes script issues related to bc by using expr. launcher-package#199 by @thatfulvioguy

Enhancement 

• Adds Scala 2.13.0-M2 support. zinc#453 by @eed3si9n and @jan0sch

Internal 

• Improves Zinc scripted testing. zinc#440 by @jvican

Contributors 

A huge thank you to everyone who’s helped improve sbt and Zinc 1 by using them, reporting bugs, improving our documentation, porting builds, porting plugins, and submitting and reviewing pull requests.

This release was brought to you by 17 contributors, according to git shortlog -sn --no-merges v1.0.3..v1.0.4 on sbt, zinc, librarymanagement, util, io, and website: Eugene Yokota, Kenji Yoshida (xuwei-k), Jorge Vicente Cantero (jvican), Dale Wijnand, Leonard Ehrenfried, Antonio Cunei, Brett Randall, Guillaume Martres, Arnout Engelen, Fulvio Valente, Jens Grassel, Matthias Kurz, OlegYch, Philippus Baalman, Sam Halliday, Tim Underwood, Tom Most. Thank you!

sbt 1.0.3 

This is a hotfix release for sbt 1.0.x series.

Bug fixes 

• Fixes ~ recompiling in loop (when a source generator or sbt-buildinfo is present). #3501/#3634 by @dwijnand
• Fixes undercompilation on inheritance on same source. zinc#424 by @eed3si9n
• Fixes the compilation of package-protected objects. zinc#431 by @jvican
• Workaround for Java returning null for getGenericParameterTypes. zinc#446 by @jvican
• Fixes test detection regression. sbt 1.0.3 filters out nested objects/classes from the list, restoring compatibility with 0.13. #3669 by @cunei
• Uses Scala 2.12.4 for the build definition. This includes fix for runtime reflection of empty package members under Java 9. #3587 by @eed3si9n
• Fixes extra / in Ivy style patterns. lm#170 by @laughedelic
• Fixes “destination file exist” error message by including the file name. lm171 by @leonardehrenfried
• Fixes JDK 9 warning “Illegal reflective access” in library management module and Ivy. lm173 by @dwijnand

Improvements 

• Adds sbt.watch.mode system property to allow switching back to old polling behaviour for watch. See below for more details.

Alternative watch mode 

sbt 1.0.0 introduced a new mechanism for watching for source changes based on the NIO WatchService in Java 1.7. On some platforms (namely macOS) this has led to long delays before changes are picked up. An alternative WatchService for these platforms is planned for sbt 1.1.0 (#3527), in the meantime an option to select which watch service has been added.

The new sbt.watch.mode JVM flag has been added with the following supported values:

• polling: (default for macOS) poll the filesystem for changes (mechanism used in sbt 0.13).
• nio (default for other platforms): use the NIO based WatchService.

If you are experiencing long delays on a non-macOS machine then try adding -Dsbt.watch.mode=polling to your sbt options.

#3597 by @stringbean

Contributors 

A huge thank you to everyone who’s helped improve sbt and Zinc 1 by using them, reporting bugs, improving our documentation, porting builds, porting plugins, and submitting and reviewing pull requests.

This release was brought to you by 15 contributors, according to git shortlog -sn --no-merges v1.0.2..v1.0.3 on sbt, zinc, librarymanagement, util, io, and website: Eugene Yokota, Dale Wijnand, Michael Stringer, Jorge Vicente Cantero (jvican), Alexey Alekhin, Antonio Cunei, Andrey Artemov, Jeffrey Olchovy, Kenji Yoshida (xuwei-k), Dominik Winter, Long Jinwei, Arnout Engelen, Justin Kaeser, Leonard Ehrenfried, Sakib Hadžiavdić. Thank you!

sbt 1.0.2 

This is a hotfix release for sbt 1.0.x series.

Bug fixes 

• Fixes terminal echo issue. #3507 by @kczulko
• Fixes deliver task, and adds makeIvyXml as a more sensibly named task. #3487 by @cunei
• Replaces the deprecated use of OkUrlFactory, and fixes connection leaks. lm#164 by @dpratt
• Refixes false positive in DSL checker for setting keys. #3513 by @dwijnand
• Fixes run and bgRun not picking up changes to directories in the classpath. #3517 by @dwijnand
• Fixes ++ so it won’t change the value of crossScalaVersion. #3495/#3526 by @dwijnand
• Fixes sbt server missing some messages. #3523 by @guillaumebort
• Refixes consoleProject. zinc#386 by @dwijnand
• Adds JVM flag sbt.gigahorse to enable/disable the internal use of Gigahorse to workaround NPE in JavaNetAuthenticator when used in conjunction with repositories override. lm#167 by @cunei
• Adds JVM flag sbt.server.autostart to enable/disable the automatic starting of sbt server with the sbt shell. This also adds new startServer command to manually start the server. by @eed3si9n

Internal 

• Fixes unused import warnings. #3533 by @razvan-panda

Contributors 

A huge thank you to everyone who’s helped improve sbt and Zinc 1 by using them, reporting bugs, improving our documentation, porting plugins, and submitting and reviewing pull requests.

This release was brought to you by 19 contributors, according to git shortlog -sn --no-merges v1.0.1..v1.0.2 on sbt, zinc, librarymanagement, and website: Dale Wijnand, Eugene Yokota, Kenji Yoshida (xuwei-k), Antonio Cunei, David Pratt, Karol Cz (kczulko), Amanj Sherwany, Emanuele Blanco, Eric Peters, Guillaume Bort, James Roper, Joost de Vries, Marko Elezovic, Martynas Mickevičius, Michael Stringer, Răzvan Flavius Panda, Peter Vlugter, Philippus Baalman, and Wiesław Popielarski. Thank you!

sbt 1.0.1 

This is a hotfix release for sbt 1.0.x series.

Bug fixes 

• Fixes command support for cross building + command. The + added to sbt 1.0 traveres over the subprojects, respecting crossScalaVersions; however, it no longer accepted commands as arguments. This brings back the support for it. #3446 by @jroper
• Fixes addSbtPlugin to use the correct version of sbt during cross building. #3442 by @dwijnand
• Fixes run in Compile task not including Runtime configuration, by reimplementing run in terms of bgRun. #3477 by @eed3si9n
• Shows actual as a potential option of inspect #3335 by @Duhemm
• Includes base directory to watched sources. #3439 by @Duhemm
• Adds an attempt to workaround intermittent NullPointerException arround logging. util#121 by @eed3si9n
• Reverts a bad forward porting. #3481 by @eed3si9n

WatchSource 

The watch source feature went through a major change from sbt 0.13 to sbt 1.0 using NIO; however, it did not have clear migration path, so we are rectifying that in sbt 1.0.1.

First, sbt.WatchSource is a new alias for sbt.internal.io.Source. Hopefully this is easy enough to remember because the key is named watchSources. Next, def apply(base: File) and def apply(base: File, includeFilter: FileFilter, excludeFilter: FileFilter) constructors were added to the companion object of sbt.WatchSource.

For backward compatiblity, sbt 1.0.1 adds += support (Append instance) from File to Seq[WatchSource].

So, if you have a directory you want to watch:

watchSources += WatchSource(sourceDirectory.value)

If you have a list of files:

watchSources ++= (sourceDirectory.value ** "*.scala").get

#3438 by @Duhemm; #3478 and io#74 by @eed3si9n

sbt 1.0.0 

Features, fixes, changes with compatibility implications 

See Migrating from sbt 0.13.x also.

• sbt 1.0 uses Scala 2.12 for build definitions and plugins. This also requires JDK 8.
• Many of the case classes are replaced with pseudo case classes generated using Contraband. Migrate .copy(foo = xxx) to withFoo(xxx). For example, UpdateConfiguration, RetrieveConfiguration, PublishConfiguration are refactored to use builder pattern.
• Zinc 1 drops support for Scala 2.9 and earlier. Scala 2.10 must use 2.10.2 and above. Scala 2.11 must use 2.11.2 and above. (latest patch releases are recommended)
• config("xyz") must be directly assigned to a capitalized val, like val Xyz = config("xyz"). This captures the lhs identifier into the configuration so we can use it from the shell later.
• Changes publishTo and otherResolvers from SettingKeys to TaskKeys. #2059/#2662 by @dwijnand
• Path.relativizeFile(baseFile, file) is renamed to IO.relativizeFile(baseFile, file).
• PathFinder’s .*** method is renamed to .allPaths method.
• PathFinder.x_!(mapper) is moved to def pair on PathFinder.
• A number of the methods on sbt.Path (such as relativeTo and rebase and flat) are now no longer in the default namespace by virtue of being mixed into the sbt package object. Use sbt.io.Path to access them again.
• sbt 1.0 renames Global as scope component to Zero to disambiguate from GlobalScope. @eed3si9n
• sbt 1.0 uses ConfigRef in places where String was used to reference configuration, such as update.value.configuration(...). Pass in Configuration, which implicitly converts to ConfigRef.
• Changes sourceArtifactTypes and docArtifactTypes from Set[String] to Seq[String] settings.
• Renames early command feature from --<command> to early(<command>).
• Drops sbt 0.12 style hyphen-separated key names (use publishLocal instead of publish-local).
• Log options -error, -warn, -info, -debug are added as shorthand for "early(error)" etc.
• sbt.Process and sbt.ProcessExtra are dropped. Use scala.sys.process instead.
• incOptions.value.withNameHashing(...) option is removed because name hashing is always on.
• TestResult.Value is now called TestResult.
• The scripted plugin is cross-versioned now, so you must use %% when depending on it.

Dropped dreprecations:

• sbt 0.12 style Build trait that was deprecated in sbt 0.13.12, is removed. Please migrate to build.sbt. Auto plugins and Build trait do not work well together, and its feature is now largely subsumed by multi-project build.sbt.
• sbt 0.12 style Project(...) constructor is restricted down to two parameters. This is because settings parameter does not work well with Auto Plugins. Use project instead.
• sbt 0.12 style key dependency operators <<=, <+=, <++= are removed. Please migrate to :=, +=, and ++=. These operators have been sources of confusion for many users, and have long been removed from 0.13 docs, and have been formally deprecated since sbt 0.13.13.
• Non-auto sbt.Plugin trait is dropped. Please migrate to AutoPlugin. Auto plugins are easier to configure, and work better with each other.
• Removes the settingsSets method from Project (along with add/setSbtFiles).
• Drops deprecated InputTask apply method and inputTask DSL method. Use Def.inputTask and Def.spaceDelimited().parsed.
• Drops deprecated ProjectReference implicit lifts. Use RootProject(<uri>), RootProject(<file>) or LocalProject(<string>).
• Drops deprecated seq(..) DSL method. Use Seq or pass in the settings without wrapping.
• Drops deprecated File/Seq[File] setting enrichments. Use .value and Def.setting.
• Drops deprecated SubProcess apply overload. Use SubProcess(ForkOptions(runJVMOptions = ..)).
• Drops toError(opt: Option[String]): Unit (equivalent to opt foreach sys.error); if used to wrap ScalaRun#run then the replacement is scalaRun.run(...).failed foreach (sys error _.getMessage)

Features 

• New incremental compiler called Zinc 1. Details below.
• The interactive shell is adds network API. Details below.

Fixes 

• Fixes test content log not showing up. #3198/util#80 by @eed3si9n
• Fixes confusing log about “Unable to parse”. lm#98 by @jvican
• Fixes console task. zinc#295 by @dwijnand
• Fixes spurious recompilations when unrelated constructor changes. zinc#288 by @smarter
• Fixes restligeist macro for old operators. #3218 by @eed3si9n
• Fixes task caching of update task. #3233 by @eed3si9n
• Fixes ncurses-JLine issue by updating to JLine 2.14.4. util#81 by @Rogach

Improvements 

• Scala Center contributed a Java-friendly Zinc API. This was a overhaul of the Zinc internal API for a good Scala integration with other build tools. zinc#304 by @jvican
• Scala Center contributed a binary format for Zinc’s internal storage. See below
• Scala Center contributed static validation of build.sbt. See below
• Library management API and parallel artifact download. See below.
• The startup log level is dropped to -error in script mode using scalas. #840 by @eed3si9n
• Replace cross building support with sbt-doge. This allows builds with projects that have multiple different combinations of cross scala versions to be cross built correctly. The behaviour of ++ is changed so that it only updates the Scala version of projects that support that Scala version, but the Scala version can be post fixed with ! to force it to change for all projects. A -v argument has been added that prints verbose information about which projects are having their settings changed along with their cross scala versions. #2613 by @jroper
• ivyLoggingLevel is dropped to UpdateLogging.Quiet when CI environment is detected. @eed3si9n
• Add logging of the name of the different build.sbt (matching *.sbt) files used. #1911 by @valydia
• Add the ability to call aggregate for the current project inside a build sbt file. By @xuwei-k
• Add new global setting asciiGraphWidth that controls the maximum width of the ASCII graphs printed by commands like inspect tree. Default value corresponds to the previously hardcoded value of 40 characters. By @RomanIakovlev.
• Revamped documentation for Scopes, and added Scope Delegation. @eed3si9n
• Ports sbt-cross-building’s ^ and ^^ commands for plugin cross building. See below.
• Adds support for cross-versioned exclusions. #1518/lm#88 by @jvican
• Adds new offline mode to the Ivy-based library management. lm#92 by @jvican
• A number of features related to dependency locking. See below.
• Improved eviction warning presentation. See below.
• A better main class detection. zinc#287 by @smarter
• For faster startup, sbt will use Java refection to discover autoImport . #3115 by @jvican
• For faster startup, reuse the same global instance for parsing. #3115 by @jvican
• Adds InteractionService from sbt-core-next to keep compatibility with sbt 0.13. #3182 by @eed3si9n
• Adds new WatchService that abstracts PollingWatchService and Java NIO. io#47 by @Duhemm on behalf of The Scala Center.
• Adds variants of IO.copyFile and IO.copyDirectory that accept sbt.io.CopyOptions(). See below for details.
• Path.directory and Path.contentOf are donated from sbt-native-packager io#38 by @muuki88
• ApiDiff feature used to debug Zinc uses Scala implementation borrowed from Dotty. zinc#346 by @Krever
• In Zinc internal, make ExtractAPI use perRunCaches. zinc#347 by @gheine

Internals 

• Adopted Scalafmt for formatting the source code using neo-scalafmt.
• Scala Center contributed a redesign of the scripted test framework that has batch mode execution. Scripted now reuses the same sbt instance to run sbt tests, which reduces the CI build times by 50% #3151 by @jvican
• sbt 1.0.0-M6 is built using sbt 1.0.0-M5. #3184 by @dwijnand

Details of major changes 

Zinc 1: Class-based name hashing 

A major improvement brought into Zinc 1.0 by Grzegorz Kossakowski (commissioned by Lightbend) is class-based name hashing, which will speed up the incremental compilation of Scala in large projects.

Zinc 1.0’s name hashing tracks your code dependendencies at the class level, instead of at the source file level. The GitHub issue sbt/sbt#1104 lists some comparisons of adding a method to an existing class in some projects:

ScalaTest   AndHaveWord class:          Before 49s, After 4s (12x)
Specs2      OptionResultMatcher class:  Before 48s, After 1s (48x)
scala/scala Platform class:             Before 59s, After 15s (3.9x)
scala/scala MatchCodeGen class:         Before 48s, After 17s (2.8x)

This depends on some factors such as how your classes are organized, but you can see 3x ~ 40x improvements. The reason for the speedup is because it compiles fewer source files than before by untangling the classes from source files. In the example adding a method to scala/scala’s Platform class, sbt 0.13’s name hashing used to compile 72 sources, but the new Zinc compiles 6 sources.

Zinc API changes 

• Java classes under the xsbti.compile package such as IncOptions hides the constructor. Use the factory method xsbti.compile.Foo.of(...).
• Renames ivyScala: IvyScala key to scalaModuleInfo: ScalaModuleInfo.
• xsbti.Reporter#log(...) takes xsbti.Problem as the parameter. Call log(problem.position, problem.message, problem.severity) to delegate to the older log(...).
• xsbi.Maybe, xsbti.F0, and sxbti.F1 are changed to corresponding Java 8 classes java.util.Optional, java.util.Supplier and java.util.Function.
• Removes unused “resident” option. zinc#345 by @lukeindykiewicz

sbt server: JSON API for tooling integration 

sbt 1.0 includes server feature, which allows IDEs and other tools to query the build for settings, and invoke commands via a JSON API. Similar to the way that the interactive shell in sbt 0.13 is implemented with shell command, “server” is also just shell command that listens to both human input and network input. As a user, there should be minimal impact because of the server.

In March 2016, we rebooted the “server” feature to make it as small as possible. We worked in collaboration with JetBrains’ @jastice who works on IntelliJ’s sbt interface to narrow down the feature list. sbt 1.0 will not have all the things we originally wanted, but in the long term, we hope to see better integration between IDE and sbt ecosystem using this system. For example, IDEs will be able to issue the compile task and retrieve compiler warning as JSON events:

{"type":"xsbti.Problem","message":{"category":"","severity":"Warn","message":"a pure expression does nothing in statement position; you may be omitting necessary parentheses","position":{"line":2,"lineContent":"  1","offset":29,"pointer":2,"pointerSpace":"  ","sourcePath":"/tmp/hello/Hello.scala","sourceFile":"file:/tmp/hello/Hello.scala"}},"level":"warn"}

Another related feature that was added is the bgRun task which, for example, enables a server process to be run in the background while you run tests against it.

Static validation of build.sbt 

sbt 1.0 prohibits .value calls inside the bodies of if expressions and anonymous functions in a task, @sbtUnchecked annotation can be used to override the check.

The static validation also catches if you forget to call .value in a body of a task.

#3216 and #3225 by @jvican

Eviction warning presentation 

sbt 1.0 improves the eviction warning presetation.

Before:

[warn] There may be incompatibilities among your library dependencies.
[warn] Here are some of the libraries that were evicted:
[warn]  * com.google.code.findbugs:jsr305:2.0.1 -> 3.0.0
[warn] Run 'evicted' to see detailed eviction warnings

After:

[warn] Found version conflict(s) in library dependencies; some are suspected to be binary incompatible:
[warn]
[warn]      * com.typesafe.akka:akka-actor_2.12:2.5.0 is selected over 2.4.17
[warn]          +- de.heikoseeberger:akka-log4j_2.12:1.4.0            (depends on 2.5.0)
[warn]          +- com.typesafe.akka:akka-parsing_2.12:10.0.6         (depends on 2.4.17)
[warn]          +- com.typesafe.akka:akka-stream_2.12:2.4.17 ()       (depends on 2.4.17)
[warn]
[warn] Run 'evicted' to see detailed eviction warnings

#3202 by @eed3si9n

sbt-cross-building 

@jrudolph’s sbt-cross-building is a plugin author’s plugin. It adds cross command ^ and sbtVersion switch command ^^, similar to + and ++, but for switching between multiple sbt versions across major versions. sbt 0.13.16 merges these commands into sbt because the feature it provides is useful as we migrate plugins to sbt 1.0.

To switch the sbtVersion in pluginCrossBuild from the shell use:

^^ 1.0.0-M5

Your plugin will now build with sbt 1.0.0-M5 (and its Scala version 2.12.2).

If you need to make changes specific to a sbt version, you can now include them into src/main/scala-sbt-0.13, and src/main/scala-sbt-1.0.0-M5, where the binary sbt version number is used as postfix.

To run a command across multiple sbt versions, set:

crossSbtVersions := Vector("0.13.15", "1.0.0-M5")

Then, run:

^ compile

#3133 by @eed3si9n (forward ported from 0.13.16-M1)

CopyOptions 

sbt IO 1.0 add variant of IO.copyFile and IO.copyDirectory that accept sbt.io.CopyOptions(). CopyOptions() is an example of pseudo case class similar to the builder pattern.

import sbt.io.{ IO, CopyOptions }

IO.copyDirectory(source, target)

// The above is same as the following
IO.copyDirectory(source, target, CopyOptions()
  .withOverwrite(false)
  .withPreserveLastModified(true)
  .withPreserveExecutable(true))

io#53 by @dwijnand

Library management API and parallel artifact download 

sbt 1.0 adds Library management API co-authored by Eugene Yokota (@eed3si9n) from Lightbend and Martin Duhem (@Duhemm) from Scala Center. This API aims to abstract Apache Ivy as well as alternative dependency resolution engines Ivy, cached resolution, and Coursier.

Parallel artifact download for Ivy engine was contributed by Jorge (@jvican) from Scala Center. It also introduces Gigahorse OkHttp as the Network API, and it uses Square OkHttp for artifact download as well.

lm#124 by @eed3si9n/@Duhemm, lm#90 by @jvican/@jsuereth and lm#104 by @eed3si9n.

Binary format for Zinc’s internal storage 

Jorge (@jvican) from Scala Center contributed a binary format for Zinc’s internal storage using Google Procol Buffer. The new format provides us with three main advantages:

1. Backwards and forwards binary compatibility at the analysis format level.
2. Faster (1.5 ~ 2x) serialization/deserialization of the analysis file.
3. Provides a better way to make the analysis file machine-independent.

zinc#351 by @jvican

Dependency locking 

Dependency locking feature is still in progress, but Jorge (@jvican) from Scala Center has added a number of related features that would should work together to allow dependency locking.

• Frozen mode to the Ivy-based library management, which makes sure that the resolution is always intransitive. lm#100
• Adds support to specify a resolver for dependencies. lm#97
• Adds “managed checksums”, which tells Ivy to skip the checksum process. lm#111

Contributors 

Too many people to thank here. See Credits

Detailed Topics 

This part of the documentation has pages documenting particular sbt topics in detail. Before reading anything in here, you will need the information in the Getting Started Guide as a foundation.

Other resources include the How to and Developer’s Guide sections in this reference, and the API Documentation

Using sbt 

This part of the documentation has pages documenting particular sbt topics in detail. Before reading anything in here, you will need the information in the Getting Started Guide as a foundation.

Command Line Reference 

This page is a relatively complete list of command line options, commands, and tasks you can use from the sbt interactive prompt or in batch mode. See Running in the Getting Started Guide for an intro to the basics, while this page has a lot more detail.

Notes on the command line 

• There is a technical distinction in sbt between tasks, which are “inside” the build definition, and commands, which manipulate the build definition itself. If you’re interested in creating a command, see Commands. This specific sbt meaning of “command” means there’s no good general term for “thing you can type at the sbt prompt”, which may be a setting, task, or command.
• Some tasks produce useful values. The toString representation of these values can be shown using show <task> to run the task instead of just <task>.
• In a multi-project build, execution dependencies and the aggregate setting control which tasks from which projects are executed. See multi-project builds.

Project-level tasks 

• clean Deletes all generated files (the target directory).
• publishLocal Publishes artifacts (such as jars) to the local Ivy repository as described in Publishing.
• publish Publishes artifacts (such as jars) to the repository defined by the publishTo setting, described in Publishing.
• update Resolves and retrieves external dependencies as described in library dependencies.

Configuration-level tasks 

Configuration-level tasks are tasks associated with a configuration. For example, compile, which is equivalent to Compile/compile, compiles the main source code (the compile configuration). Test/compile compiles the test source code (test test configuration). Most tasks for the compile configuration have an equivalent in the test configuration that can be run using a Test/ prefix.

• compile Compiles the main sources (in the src/main/scala directory). Test/compile compiles test sources (in the src/test/scala/ directory).
• console Starts the Scala interpreter with a classpath including the compiled sources, all jars in the lib directory, and managed libraries. To return to sbt, type :quit, Ctrl+D (Unix), or Ctrl+Z (Windows). Similarly, Test/console starts the interpreter with the test classes and classpath.
• consoleQuick Starts the Scala interpreter with the project’s compile-time dependencies on the classpath. Test/consoleQuick uses the test dependencies. This task differs from console in that it does not force compilation of the current project’s sources.
• consoleProject Enters an interactive session with sbt and the build definition on the classpath. The build definition and related values are bound to variables and common packages and values are imported. See the consoleProject documentation for more information.
• doc Generates API documentation for Scala source files in src/main/scala using scaladoc. Test/doc generates API documentation for source files in src/test/scala.
• package Creates a jar file containing the files in src/main/resources and the classes compiled from src/main/scala. Test/package creates a jar containing the files in src/test/resources and the class compiled from src/test/scala.
• packageDoc Creates a jar file containing API documentation generated from Scala source files in src/main/scala. Test/packageDoc creates a jar containing API documentation for test sources files in src/test/scala.
• packageSrc: Creates a jar file containing all main source files and resources. The packaged paths are relative to src/main/scala and src/main/resources. Similarly, Test/packageSrc operates on test source files and resources.
• run <argument>* Runs the main class for the project in the same virtual machine as sbt. The main class is passed the arguments provided. Please see Running Project Code for details on the use of System.exit and multithreading (including GUIs) in code run by this action. Test/run runs a main class in the test code.
• runMain <main-class> <argument>* Runs the specified main class for the project in the same virtual machine as sbt. The main class is passed the arguments provided. Please see Running Project Code for details on the use of System.exit and multithreading (including GUIs) in code run by this action. Test/runMain runs the specified main class in the test code.
• test Runs all tests detected during test compilation. See Testing for details.
• testOnly <test>* Runs the tests provided as arguments. * (will be) interpreted as a wildcard in the test name. See Testing for details.

• testQuick <test>* Runs the tests specified as arguments (or all tests if no arguments are given) that:

  1. have not been run yet OR
  2. failed the last time they were run OR
  3. had any transitive dependencies recompiled since the last successful run * (will be) interpreted as a wildcard in the test name. See [Testing][Testing] for details.

General commands 

• exit or quit End the current interactive session or build. Additionally, Ctrl+D (Unix) or Ctrl+Z (Windows) will exit the interactive prompt.
• help <command> Displays detailed help for the specified command. If the command does not exist, help lists detailed help for commands whose name or description match the argument, which is interpreted as a regular expression. If no command is provided, displays brief descriptions of the main commands. Related commands are tasks and settings.
• projects [add|remove <URI>] List all available projects if no arguments provided or adds/removes the build at the provided URI. (See multi-project builds for details on multi-project builds.)
• project <project-id> Change the current project to the project with ID <project-id>. Further operations will be done in the context of the given project. (See multi-project builds for details on multiple project builds.)
• ~ <command> Executes the project specified action or method whenever source files change. See Triggered Execution for details.
• < filename Executes the commands in the given file. Each command should be on its own line. Empty lines and lines beginning with ’#’ are ignored
• + <command> Executes the project specified action or method for all versions of Scala defined in the crossScalaVersions setting.
• ++ <version|home-directory> <command> Temporarily changes the version of Scala building the project and executes the provided command. <command> is optional. The specified version of Scala is used until the project is reloaded, settings are modified (such as by the set or session commands), or ++ is run again. <version> does not need to be listed in the build definition, but it must be available in a repository. Alternatively, specify the path to a Scala installation.
• ; A ; B Execute A and if it succeeds, run B. Note that the leading semicolon is required.

• eval <Scala-expression> Evaluates the given Scala expression and returns the result and inferred type. This can be used to set system properties, as a calculator, to fork processes, etc … For example:

  > eval System.setProperty("demo", "true")
  > eval 1+1
  > eval "ls -l" !
  

Commands for managing the build definition 

• reload [plugins|return] If no argument is specified, reloads the build, recompiling any build or plugin definitions as necessary. reload plugins changes the current project to the build definition project (in project/). This can be useful to directly manipulate the build definition. For example, running clean on the build definition project will force snapshots to be updated and the build definition to be recompiled. reload return changes back to the main project.
• set <setting-expression> Evaluates and applies the given setting definition. The setting applies until sbt is restarted, the build is reloaded, or the setting is overridden by another set command or removed by the session command. See .sbt build definition and Inspecting Settings for details.
• session <command> Manages session settings defined by the set command. It can persist settings configured at the prompt. See Inspecting Settings for details.
• inspect <setting-key> Displays information about settings, such as the value, description, defining scope, dependencies, delegation chain, and related settings. See Inspecting Settings for details.

Sbt runner arguments 

When launching the sbt runner from the OS shell, various system properties or JVM extra options can be specified to influence its behaviour.

sbt JVM options and system properties 

If the JAVA_OPTS and/or SBT_OPTS environment variables are defined when sbt starts, their content is passed as command line arguments to the JVM running sbt.

If a file named .jvmopts exists in the current directory, its content is appended to JAVA_OPTS at sbt startup. Similarly, if .sbtopts and/or /etc/sbt/sbtopts exist, their content is appended to SBT_OPTS. The default value of JAVA_OPTS is -Dfile.encoding=UTF8.

You can also specify JVM system properties and command line options directly as sbt arguments: any -Dkey=val argument will be passed as-is to the JVM, and any -J-Xfoo will be passed as -Xfoo.

See also sbt --help for more details.

sbt JVM heap, permgen, and stack sizes 

If you find yourself running out of permgen space or your workstation is low on memory, adjust the JVM configuration as you would for any java application.

For example a common set of memory-related options is:

export SBT_OPTS="-Xmx2048M -Xss2M"
sbt

Or if you prefer to specify them just for this session:

sbt -J-Xmx2048M -J-Xss2M

Boot directory 

sbt is just a bootstrap, the actual meat of sbt, the Scala compiler and standard library are by default downloaded to the shared directory $HOME/.sbt/boot/.

To change the location of this directory, set the sbt.boot.directory system property. A relative path will be resolved against the current working directory, which can be useful if you want to avoid sharing the boot directory between projects. For example, the following uses the pre-0.11 style of putting the boot directory in project/boot/:

sbt -Dsbt.boot.directory=project/boot/

Terminal encoding 

The character encoding used by your terminal may differ from Java’s default encoding for your platform. In this case, you will need to specify the file.encoding=<encoding> system property, which might look like:

export JAVA_OPTS="-Dfile.encoding=Cp1252"
sbt

HTTP/HTTPS/FTP Proxy 

On Unix, sbt will pick up any HTTP, HTTPS, or FTP proxy settings from the standard http_proxy, https_proxy, and ftp_proxy environment variables. If you are behind a proxy requiring authentication, you need to pass some supplementary flags at sbt startup. See JVM networking system properties for more details.

For example:

sbt -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword

On Windows, your script should set properties for proxy host, port, and if applicable, username and password. For example, for HTTP:

sbt -Dhttp.proxyHost=myproxy -Dhttp.proxyPort=8080 -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword

Replace http with https or ftp in the above command line to configure HTTPS or FTP.

Other system properties 

The following system properties can also be passed to sbt: