How to make SBT download scala library sources

Posted by Mathias in [scala]

17 Dec 2010

Being in the process of setting up a new machine for Scala development I once again found myself scratching my head over a question I already faced several times in the past:
How to persuade SBT to automatically download not just the Scala standard library jar for my target Scala version but also the corresponding sources?

Since readily available information about this particular configuration problem still appears to be somewhat scarce I’m writing up this short post mostly for my own reference, but I figure that others might be interested in this too.

First, forget about trying to find some “hidden” setting in your SBT project definition enabling Scala library source download! It does not exist (at least not in SBT version 0.7.x). Rather, there are these two things you need to do in order to whip SBT into submission:

  1. Create an alternative configuration file for your SBT launcher.
  2. Make the SBT launcher use it.

These are the steps in detail:

  • Find your sbt-launcher-0.7.x.jar file.
    Since I’m on OS/X and use SBT via Homebrew mine lives at /usr/local/Cellar/sbt/0.7.5.RC0/libexec/sbt-launch-0.7.5.RC0.jar
  • Extract the sbt.boot.properties from the sbt sub directory in the launcher jar
  • Fire up your favorite editor and change line 3 to classifiers: sources (uncomment the line)
  • Find the sbt script file you created during your SBT setup (e.g. ~/bin/sbt, or, when using Homebrew, /usr/local/Cellar/sbt/0.7.x/bin/sbt)
  • Add the path to your tweaked sbt.boot.properties file, prepended with an ’@’ character and in double quotes, as the second-to-last argument of the java call.

This is what my sbt script file looks like:

#!/bin/sh
java -Xmx768M -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256m \
     -jar /usr/local/Cellar/sbt/0.7.5.RC0/libexec/sbt-launch-0.7.5.RC0.jar \
     "@/usr/local/Cellar/sbt/0.7.5.RC0/libexec/sbt.boot.properties" \
     "$@"

Once you have completed these steps SBT should happily download the scala-...-sources.jar files for the Scala compiler and standard library for any new project you create. To have SBT do this for an existing project you have to manually delete the project/boot/scala-{version} directory before performing an ‘sbt update’ (SBT does not fetch additional source artifacts if the main jar is already present).

Cheers,
Mathias

PS: Thanks a lot to @hseeberger for giving me the key starting points for getting this done.

Update 2010-12-17

Once you have a custom sbt.boot.properties file, there are also other ways to supply it to the SBT launcher. This thread on stackoverflow contains more information on this, the key points being:

The launcher may be configured in one of the following ways in increasing order of precedence:

  • Replace the /sbt/sbt.boot.properties file in the jar.

  • Put a configuration file named sbt.boot.properties on the classpath. Put it in the classpath root without the /sbt prefix.

  • Specify the location of an alternate configuration on the command line. This can be done by:

    • either specifying the location as the system property sbt.boot.properties
    • or as the first argument to the launcher prefixed by ’@’.

The system property has lower precedence. Resolution of a relative path is:

  • first attempted against the current working directory,
  • then against the user’s home directory,
  • and then against the directory containing the launcher jar.

An error is generated if none of these attempts succeed.

View Comments