SBT ~ Scala's Simple Build Tool Series, Part 1. What is SBT and how do I use it?

Scala's Simple Build Tool is an all-in-one plug-n-play build and dependency management tool. Despite the name, SBT is often criticized for being difficult to use and extend, and for marginalizing the traditional Java ecosystem build tools - Maven and Ant. I too have had some difficulty understanding the internal concepts of SBT, so I decided to write a series of blog posts on the topic, both to help myself gain a deeper understanding and to help others who are struggling with understanding the tool.


What SBT is:
SBT is the build tool of choice for Scala projects. Like other build tools for other languages SBT's purpose is to compile and publish applications written in Scala. It is a command-line tool written in scala. It defines both an API and a Domain Specific Language (DSL) for building and testing scala projects, managing dependencies, publishing projects, and running them locally. While the SBT Getting Started Guide is helpful for getting off of the ground, it can be a little difficult to grok, and will probably take several readings to fully understand. Additionally, you are probably going to have to read the SBT source code to really get how to use SBT to its fullest potential. The SBT API documentation is a good resource for looking up method signatures and predefined value names, but it lacks a blow-by-blow explanation of what those methods do or what they expect as parameters beyond basic type definitions for parameters and returns. 


This can be troublesome, because many of the methods are symbols (Scala allows methods like ~= and <<=) or require understanding of some basic Scala concepts like defining and applying anonymous functions, strongly typed generic collections,  and traits that a newly minted user of Scala might not fully understand. As always, reading the source code is the best way to really understand an application, and I encourage you to do so. Also, as the project is open source, please feel free to contribute better documentation and examples by forking the xsbt github project. I hope to provide here a companion guide to SBT that will deepen my own and others' understanding of SBT, as well as some helpful hints for getting started with SBT.


SBT Requirements:

1. JVM 1.5 or later.
2. The latest scala distro.
3. The latest sbt-launch.jar.
4. Paul Phillips' excellent sbt-extras sbt launch script.

Installation:

1. Download and install sbt-launch.jar and place it in ~/bin. DO NOT put sbt-launch.jar in your CLASSPATH. You don't need to do that.
2. Clone git://github.com/paulp/sbt-extras.git.
3. cd into the cloned sbt-extras repo and copy sbt to ~/bin.
4. chmod u+x ~/bin/sbt

That's it! Congratulations, you have installed SBT.

A Simple Hello World! project:

Now let's set up a simple Hello World scala example. SBT expects a certain project structure. For historical reasons, this project structure is similar to the project structure used by Apache Maven projects:

lib/
   <unmanaged jars go here>
src/
   main/
      resources/
         <files to include in project jar go here>
      scala/
         <main scala source files go here>
      java/
         <main Java source files go here>
   test/
      resources/
         <files to be included in the project test jar go here>
      scala/
         <scala test source files go here>
      java/
         <Java test source files go here>
project/
         <project build scala files go here>

1. Create a helloProject directory
2. cd to helloWorld
3. mkdir lib
4. mkdir -p src/main/resources
5. mkdir src/main/scala
6. mkdir src/main/java
7. mkdir -p src/test/resources
8. mkdir src/test/scala
9. mkdir src/test/java
10. mkdir project

Now that you have defined your project structure, let's create our first .sbt build definition file. Open your favorite text editor and enter the following, including the empty lines:


name := "helloWorld"


version := "1.0"


scalaVersion := "2.9.1"


Save the file as helloWorld/build.sbt.


build.sbt Explanation
build.sbt is a SBT build definition file. Build definition files contain Scala expressions and function definitions using the SBT DSL. What you have just defined is a list of settings that SBT will use when building and running your projects.


Remember when I said that you would need to understand a few basic Scala concepts to understand SBT? Well here is where you get to learn about a few of them. Each line of the build.sbt file above is Scala code. Each line is a separate Scala expression that will be applied to the default list of settings to produce a new list of settings that SBT will use to build your project. The newlines are delimiters used by SBT to separate each expression. The identifiers on each line (name, version, etc.) represent predefined sbt.Keys.  The := on each line calls the sbt.Keys.:= method with the argument string that follows it. The := returns a generically typed setting of type Setting[T]. Since all of our settings are strings, our build.sbt defines a list of Setting[String] objects.


Now, since we are using the extremely helpful sbt-extras sbt script, we need to define a build.properties file in our project's project directory. Fire up your favorite text editor again, and enter the following text:


sbt.version=0.11.2


Save the file as helloWorld/project/build.properties.


build.properties Expanation
project/build.properties is used by the sbt-extras sbt script to decide which version of sbt to use to build your project. The script will download the appropriate version of sbt and execute it to build your project.


Finally, lets create a simple Scala application that will print "Hello World!". Fire up the text editor again and enter the following Scala code:


object Hello{
   def main(args: Array[String]) = println("Hello World!)
}


Save the file in helloWorld/src/main/scala/HelloWorld.scala.


Now we're ready to run sbt for the first time. Go to the console, cd into the helloWorld directory, and type sbt. After the prompt, type run. The sbt console will run, download the necessary dependencies (the correct scala version, for example) and print "Hello World!". Type exit to leave sbt.


That's it. Now you know how to define a project to use sbt with a simple build definition. Hopefully, this helps you get started.


Next Article:
The next article will focus on the different types of Settings provided by SBT out of the box. Happy Hacking!


Credits:

harrah/xsbt. 2012 Jan 10. _root_.
   harrah / xsbt. <http://harrah.github.com/xsbt/latest/api/index.html#package>. Accessed 2012 Jan 10.

harrah/xsbt. 2012 Jan 10. harrah/xsbt.
   harrah/xsbt. <https://github.com/harrah/xsbt>. Acessed 2012 Jan 10.


harrah/xsbt. 2012 Jan 10. Directory structure.
   harrah/xsbt. <https://github.com/harrah/xsbt/wiki/Getting-Started-Directories>. Accessed 2012 Jan 10.


harrah/xsbt. 2012 Jan 10. Setup.
   harrah/xsbt. <https://github.com/harrah/xsbt/wiki/Getting-Started-Setup>. Accessed 2012 Jan 10.

harrah/xsbt. 2012 Jan 10. Setup Notes.
   harrah/xsbt. <https://github.com/harrah/xsbt/wiki/Setup-Notes>. Accessed 2012 Jan 10.


harrah/xsbt. 2012 Jan 10. Welcome!.
   harrah/xsbt. <https://github.com/harrah/xsbt/wiki/Getting-Started-Welcome>. Accessed 2012 Jan 10.


Phillips, Paul. 2012 Jan 10. paulp/sbt-extras.
   paulp/sbt-extras. <https://github.com/paulp/sbt-extras>. Accessed 2012 Jan 10. 


van Zyl, J. 2012 Jan 10. Introduction to the Standard Directory Layout.
   Apache Maven Project. <http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html>. Accessed 2012 Jan 10.