Quick Start to using Scala Simple Build Tool (sbt)

After you finish a basic Hello World program in Scala, and want to start your first real Scala project, you will need to choose a build tool.  While you can use tools like ant or maven, Simple Build Tool (sbt in short) is a very popular option among Scala programmers.  In this post, I describe the bare minimum you need to know to quickly get started on using sbt.

Step 1: Install sbt

On a Mac it is as simple as 

sudo port install sbt

or, if you are using homebrew,

brew install sbt

For other operating systems, please see the official Getting Started Setup page.

Step 2: Create your project's directory structure

myproject/
    src/
        main/
            scala/
            java/
            resources/
        test/
            scala/
            java/
            resources/

myproject is your project's top-level directory. resources contain non-code files that are packaged up together with your project, like image or data files.

Step 3: Start writing your project's code
Let's just use a Hello World program.  Create myproject/src/main/scala/HelloWorld.scala that contains the following code:

import org.slf4j._

object HelloWorld {
    def main(args: Array[String]) = {
        val logger:Logger = LoggerFactory.getLogger("MyLogger");
        logger.info("Hello World");
    }
}

We use the slf4j logging library instead of a simple println in order to demonstrate how external dependencies are specified in sbt.

Step 4: Create a build definition file
Put the following lines in myproject/build.sbt. Note that the blank lines below ARE absolutely necessary.

name := "Hello World"

version := "1.0"

scalaVersion := "2.9.1"

libraryDependencies ++= Seq(
  "org.slf4j" % "slf4j-api" % "1.6.4",
  "org.slf4j" % "slf4j-simple" % "1.6.4"
)

The libraryDependencies setting specifies the managed dependencies, i.e., the dependencies which are automatically downloaded for you from the Maven repositories. A dependency is specified as groupId % artifactId % revision. Conventions for groupId, artifactId and revision are discussed at http://maven.apache.org/guides/mini/guide-naming-conventions.html. The automatically downloaded dependencies are usually stored in ~/.ivy2/cache.

You don't have to use maven if you don't want to. Instead you can use unmanaged dependencies. Just put the appropriate jars in myproject/lib, and don't specify them in the libraryDependencies setting.

Step 5: Compile, run and package your program

cd myproject
sbt run

The first time you run sbt, it will download all the dependencies (sometimes including the scala version specified in the scalaVersion setting). This means that it will take some time. Subsequent runs will be much faster.

If you just want to compile,  type:

sbt compile

You can set up sbt to automatically compile your program as soon as any source file changes.  To do so, type:

sbt ~compile

Continuous compilation is a great time-saver.

To package your program for distribution as a jar, type:

sbt package

A jar containing all your compiled classes and resources from myproject/src/main/resources will be found in myproject/target/scala-YOUR_SCALA_VERSION_HERE. Note that dependencies are NOT included in the jar. To include all dependencies into the output jar, you will need to use the assembly plugin. See the next step for pointers to info about plugins.

Step 6: Read the official Getting Started Guide
This post only aims to get you quickly started on sbt.  There are tons of features it does not cover -- multiple projects and plugins, just to name two very important ones.  To learn how to use these features and to understand the fundamental principles behind sbt (which is in fact just a Scala Domain Specific Language), please read the Official Getting Started Guide.  It is long and sometimes too deep, but very useful indeed.