Zero to a Scala SBT Project

SBT (Simple Build Tool) is a build environment for Scala (and Java) applications. It features Maven-style dependency management, a build definition language, pluggable architecture and an interactive shell. Roughly akin to Maven for Java and Rake for Ruby, SBT can be used to build, run and deploy apps and can work alongside both text editors and full IDE’s.

In this tutorial I’ll demonstrate how to create a new Scala project (“HelloSBT”) from scratch with SBT, and an extra section on how to load the generated project into Intellij. This tutorial has been tested with SBT 0.12.2 and Scala 2.10.0

Part 1 - Setup

1. If you don’t already have it on your system, download Java’s JDK 6 or 7 and install it.
2. Download Scala 2.10 and install it in /usr/local (eg: /usr/local/scala-2.10.0)
3. Download and install SBT. Homebrew users can run brew install sbt but it’s also pretty easy to install on Windows and Linux.

Part 2 - A Basic Hello SBT App

In which we create a very simple Scala app and SBT project from scratch, starting in your system shell (eg BASH) and finishing with a running example.

$ mkdir hellosbt
$ cd hellosbt
$ mkdir -p src/main/scala
$ echo 'object Hi extends App { println("Hello SBT") }' > src/main/scala/Hi.scala
$ sbt run

You should see the output after SBT initialized and compiles your app: Hello SBT

To finish this basic SBT project you need a build definition file, stored in build.sbt at the root of the project. The .sbt file format is a domain specific language (DSL) based on but not exactly like Scala and contains mainly name-value pairs and library dependency management.

$ cat << EOF > build.sbt

organization := "scala"

name := "HelloSBT"

version := "1.0"

scalaVersion := "2.10.0"

EOF

Since you don’t need any external libraries at this point, your build.sbt file just defines your project information and the desired scala version.

With your project completed, bring up the SBT shell and test-drive just a few of the functions to get acquainted.

To avoid confusion the $ prompt indicates your system shell and the > prompt the SBT shell.

$ sbt
> about      # information about sbt, plugins, and your project
> help
> tasks      # project-specific task, eg run, compile, test, package
> clean      # cleans up (deletes) all temporary and build files
> compile    # 'run' invokes compile, but useful as an invididual step
> run        # runs the given class, or the main class if none is specified
> package    # builds an artifact from your project, eg .jar or .war file

After running package, exit the shell and check out your new project’s artifact:

target/scala-2.10/hellosbt_2.10-1.0.jar

Good news, you’ve created an SBT project!

Part 3 - Using External Libraries

Better news, since Scala is a JVM language you have access to the full (and massive) collection of open source Java libraries. The main distribution mechanism for Java libraries is Maven artifact repositories, and SBT has full support for adding them to your project. In this section we’ll add the popular Joda-Time Date/Time management library to the project and update the application to demonstrate it.

First open the build.sbt file created in Part 2 and add the following lines:

libraryDependencies += "joda-time" % "joda-time" % "1.6.2"

Note: SBT requires that settings in build.sbt must be separate by at least one blank line.

Now edit the Hi.scala file to make use of this new library, then we can try it out.

object Hi extends App {
  val now = new org.joda.time.DateTime()
  println("Hi SBT, the time is " + now.toString("hh:mm aa"))
}

$ sbt run

When you hit SBT will download the joda-time library from a public Maven repository and cache it in a local repository. You can find the library in ~/.ivy/cache since SBT uses the Java-based Apache Ivy project for library management.

After the library is downloaded and your project is compiled, SBT will display the new greeting with the current time.

Extra Credit: Open your SBT project in Intellij IDEA

I’m not going to argue the benefits of IDE’s vs Text Editors here, and will gamely sidestep the Eclipse vs Intellij IDE battle since this article is already long enough. However if you do like IDE’s and are amenable to using the free Intellij IDEA IDE, here’s how to get it to open your new SBT project so you can write and execute applications from inside without going to the command line.

This step uses Mike Peltonen’s excellent sbt-idea plugin for SBT to convert SBT projects to Intellij format. You’ll need to install the Intellij IDEA and its Scala plugin, which are free and open source. See my previous blog post Zero to Hello World in Scala for download links and installation instructions.

When Intellij is installed, run this to install the sbt-idea plugin globally :

$ mkdir -p ~/.sbt/plugins
$ cat << EOF >> ~/.sbt/plugins/build.sbt

resolvers += "Sonatype snapshots" at "http://oss.sonatype.org/content/repositories/snapshots/"

addSbtPlugin("com.github.mpeltonen" % "sbt-idea" % "1.3.0-SNAPSHOT")

EOF

Then run this in your hellosbt directory to generate the IDEA project:

$ sbt gen-idea

You can now open this project directly in Intellij IDEA. To execute the app, right-click on the Hi.scala file in the Project tab and choose Run Hi.main().

Next Steps

At this point you can create a simple SBT project with dependencies and optionally edit it in an IDE (or using a regular text editor).

If you’re still learning Scala I recommend picking up the classic Programming in Scala: A Comprehensive Step-by-Step Guide by one of the creators of the language. It’s a long read but covers the majority of the language and progresses at an easy pace.

A good next step is to start developing your first Scala web application, using one of the common Scala web frameworks such as Lift, Play or Scalatra.