The sbt 0.6.x series attempts to merge ideas from xsbt (experimental sbt components) into the main sbt. It should be considered less stable currently than 0.5.x because of extensive internal changes to sbt.
Please point out gaps in the documentation, areas that need clarification, or anything you'd like more details about. Your time experimenting is appreciated!
There are currently three major improvements in 0.6.x over previous versions:
The ongoing aim for the rest of the series is to further modularize sbt and address issues that will come up due to these changes.
The launcher has been substantially rewritten so that it is not specific to sbt. For complete details on it, see 0_6_Launcher. That page describes the new launcher, including how to make an application launchable. Basically, you provide a configuration file to the launcher and have your application entry point implement an interface.
The following can now be done by modifying the default sbt configuration file for the launcher:
You can also set up separate scripts to use different configuration files. For example, you might have a 'sbt-quick' script. The configuration file used could specify that new projects are set up without prompting, but instead use your specified defaults for properties.
The new launcher can only launch the new 0.6.x series of sbt and the new series of sbt requires the new launcher.
I've managed to keep the launcher jar the same size and start up in the same time. However, the corresponding version of sbt is about 30% slower on startup and is bigger in size. This is partly due to a temporary duplication of some functionality between sbt and the new xsbt components during the transition.
Now is a good time for users to point out usability issues and possible improvements related to launching- startup, reload, and retrieving sbt and Scala. The Ivy "errors" about unknown resolvers that are especially apparent in the launcher (including the previous version of the launcher) is a known issue to the Ivy developers. See issue IVY-758 as reported by the Gradle developers.
The new launcher provides essential support for implementing the separation of Scala versions. It also provided an opportunity to clean up cross-building and project reloading. Please note the changes in the following section on compatibility.
The version used to run sbt and used for compiling the project definition is set by the build property def.scala.version. The only valid value for this property is 2.7.7. This means that sbt runs in 2.7.7 and your project definition is compiled against 2.7.7. As described below, the version of Scala used to build your project is independent of this version.
The 'build.scala.versions' property is a whitespace separated list of versions to use when cross building (that is, when doing '+compile' or similar). The first version in the list is used for single-version actions (actions not prefixed with '+'). Allowed versions should (in theory) be any Scala version 2.7.2 or later, including 2.8.0.Beta1-RC6, 2.8.0-SNAPSHOT, and 2.8.0-20091230.025722-+.
To change the version of Scala used for building at the interactive prompt or as part of a sequence of commands from the command line, use '++version'. 'version' does not need to be listed in 'build.scala.versions'. To set the version and run an action, use '++version action' (space between version and action). In both cases, the new version is used until the next '++' or on 'reload' or a restart. '+action' is now expanded to '++v1 action', '++v2 action', ... for versions v1,v2,... in 'build.scala.versions'.
It should be easy to use locally built Scala versions now. Declare local versions by overriding the 'localScala' method in your project definition. This method should return a Seq[ScalaInstance], where the 'defineScala' method is used to create ScalaInstances. The two variants are:
> console-project ... > localScala
As an example, assume scalaHome is appropriately set. The following registers the result of 'ant quick' with sbt:
override def localScala = defineScala("2.8.0-quick", (scalaHome / "build" / "pack" ).asFile) :: Nil
You could then include '2.8.0-quick' in build.scala.versions or as a valid version to switch to as in:
Because the build and definition Scala versions are now separated, the way to declare the options for forking the run action has changed. The following examples demonstrate the new way:
override def fork = forkRun override def fork = forkRun(new File("different-working-directory")) override def fork = forkRun("-Xmx8G" :: Nil) override def fork = forkRun( Some(new File("different-working-directory")), forkRun("-Xmx8G" :: Nil) )
sbt now supports test frameworks through the uniform test interface, which itself is a work in progress. This should make sbt more independent of test frameworks that can implement the test interface. sbt only needs to know the name of the class implementing the interface. sbt no longer needs to be recompiled in order to support new frameworks, new versions of frameworks, or frameworks compiled against different Scala versions.
Josh Cough has implemented this interface for ScalaTest and Sweet, Rickard Nilsson has done it for ScalaCheck, and Eric Torreborre has done it for specs. You will need the latest snapshots of these libraries.
Other test frameworks that implement the interface will be added to sbt's list of known frameworks. It is easy enough to use a framework not yet known to sbt, however. For example, if a new test framework implements the interface and sbt has not been updated to know about it yet, use that snapshot as a normal library in your project and add the following to your project definition:
override def testFrameworks = super.testFrameworks ++ new TestFramework("org.example.ExampleFramework")
where org.example.ExampleFramework is replaced with the name of the class that implements the test interface.
To use the 0.6.x series, you need to get the new launcher and set up a script to run it as before. I call my script xsbt to avoid confusion with the stable 0.5.x series. Something like:
java -jar xsbt-launch-0.6.9.jar "[email protected]"
On an existing project, you need to set sbt.version to 0.6.9. You will be prompted for the version(s) of Scala to use for your project, since this is a new property (build.scala.versions, as mentioned in the Scala Version Handling section). Check the Compatibility section above when using 0.6.x on an existing project. Again, there are some unavoidable, but hopefully minor, incompatibilies so try it out on a test project or a branch.
The procedure for building sbt locally has changed, but it still uses the last stable sbt release (0.5.6) to build. sbt is currently split across two projects for this experiment, so there are two 'publish-local's that need to be run. From scratch, setting up sbt 0.6.x locally would look like:
$ git clone git://github.com/harrah/xsbt.git $ cd xsbt $ sbt update proguard "project Compile" publish-local "project Test" publish-local $ cd .. $ git clone git://github.com/harrah/sbt.git $ cd sbt $ git checkout --track -b using-xsbt origin/using-xsbt $ cd scripted $ sbt update publish-local $ cd .. $ sbt update publish-local
The launcher jar created by the proguard action is located at xsbt/target/xsbt-launch-0.6.x.jar.