Loader  

Scala and Sbt Versions

This page describes how the sbt loader helps you use different versions of Scala and sbt to build your projects. For details on how it can be used to launch other applications besides sbt in a similar manner, see GeneralizedLauncher.

Previously

sbt versions before 0.3.8 were compiled against a specific version of Scala and test libraries (ScalaCheck, ScalaTest, and specs). You could only use this version of Scala to build your project unless you built sbt from source. You could also only use the version of a test library that was binary compatible with the version of Scala that sbt was compiled with.

Now

This has changed with sbt 0.3.8. The distributed jar is no longer the main sbt jar. It is instead a loader that has the classes it needs from Ivy and Scala included in the same jar (after shrinking with Proguard). This loader reads the versions of Scala and sbt to use to build the project from the project/build.properties file. If this is the first time the project has been built with those versions, the loader downloads the appropriate versions to your project/boot directory. The sbt loader will then load the right version of the main sbt builder using the right version of Scala.

Motivation

When a new version of sbt is released, you only have to do:

> set sbt.version 0.7.7
> reload

and the sbt loader will download the new version of sbt to build your project. Note that new features occasionally require updating the loader.

The loader enables building against multiple versions of Scala. To use this feature, list multiple Scala versions in your build.scala.versions property. Then, prefix the action to run with +.

$ sbt
> set build.scala.versions 2.7.7 2.8.1 2.7.2
> reload
> +compile

or

$ sbt "+compile"

outputPath and managedDependencyPath have the version of Scala being used for the build appended to their path. By default, this means:

 target -> target/scala_2.7.2
 lib_managed -> lib_managed/scala_2.7.2

If you use custom output directories or you redefine paths, you will want to wrap them in crossPath, which will append this component. For example, outputPath is defined as:

  def outputPath = crossPath(outputRootPath)
  def outputRootPath = path("target")

Setup

  1. Because Proguard embeds the Scala+Ivy classes the loader needs, the sbt script now looks like:
  2.   java -Xmx512M -jar sbt-launcher.jar "$@"
This means Scala doesn't have to be installed already.
  1. Run sbt in an existing project and you will be prompted for the versions of Scala and sbt to use. Currently, Scala versions 2.7.2 and later and sbt 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.7.5, and 0.7.7 are available options. The sbt launcher will download the proper version of Scala and the requested version of the sbt builder and put them in project/boot.
  2. The launcher will use these downloaded jars to build your project.
  3. Proceed using sbt.

Offline Usage

The sbt loader requires an internet connection to download the selected versions of the Scala and main sbt builder jars. Once the jars are downloaded, the loader does not need a connection to build projects on that machine unless you use a different version of Scala or sbt. Cleaning the Ivy cache, such as with the clean-cache action, will require downloading the jars again, however.

The loader downloads the jars to the project/boot directory in a project. This directory can be copied between projects. Therefore, once you have a project/boot directory for the desired versions of sbt and Scala, you can copy this directory to other projects, including ones on other machines.