Posted by & filed under Content - Highlights and Reviews, Programming & Development.

A guest post by Chris Hodapp, who since completing two Google Summers of Code with the Scala team, has spent most of his free time looking for ways to do interesting things both with and to Scala, and can be reached on Twitter @clhodapp.

When you build your first nontrivial project in a new (compiled) language, you are likely to be faced with the question of which build system to use. In Scala, this will likely mean considering sbt, Gradle, and that old Java-ecosystem favorite, Maven. Despite being the most “standard” choice for the Scala ecosystem, you will probably see a lot of commentary online stating that sbt is “too complex.” I’m here to tell you that, while sbt is very powerful, it is not something you should be afraid of. In truth, sbt builds can be as simple or as complex as you want them to be (with the minimum complexity level being significantly below that of other build systems).

Before proceeding any further, I recommend that you install sbt, using one of the official installations methods. Note: if you are on a Mac, I recommend installing sbt with Homebrew.

So, let’s get started. We’ll be working in a terminal. Presumably, you have (or plan to have) your source files in a directory somewhere on your system. Change (cd) to that directory and create a file called build.sbt. Let’s define a few basic settings by populating the file with the following lines:

Note: skipping lines is mandatory.

So, what do these settings do? Well, name sets a name for your project. This name will be used in generated artifacts (Note that artifacts is just a fancy word we use in the Java ecosystem to mean “compiled things”. Usually, we mean .jar files, which serve the dual role of libraries and executables for Java-ecosystem projects). An organization is really a namespace for project names and is supposed to prevent clashes between projects with common names (e.g. util). It’s convention to make it the reverse-form of a domain name that either you or your company owns. The scalaVersion setting specifies the version of Scala that you want to build against. You don’t need to have this version installed, since sbt will fetch the version you specify from the Internet. The final setting, version, just specifies the current version of your project. It’s convention to append the string -SNAPSHOT for non-release versions.

With that out of the way, it’s time to actually build your source files. Run the sbt command. The sbt shell will load, giving you a prompt of “> “. Here, you can enter compile and sbt will build all of the Scala and Java source files in the directory you started the shell in. You can enter run to run your program (if it is runnable). You can enter package to generate a .jar file, which is placed in a subdirectory of the target directory, which sbt will generate in the directory where you ran its shell (the subdirectory of target will be named after a version of Scala, e.g., scala-2.10).

Note that this will only work if you keep all of your source files in the same directory. This is fine for very simple projects, but at some point, your project will become more complex, and you will want to have a source directory with several subdirectory levels. Of course, sbt can handle this type of configuration. Create a directory tree rooted in the current directory that looks like the following:


As you’ve probably guessed, you should move your Scala sources into src/main/scala, while your Java sources should be moved into src/main/java. You can place application resource files (such as image assets) in the src/main/resources directory. You are free to organize files however you wish within these directories, since sbt will search them recursively. The test directory exists to hold any tests that you wish to add to your project in the future, and you can have the same subdirectories as main. Before you add your first test, be sure to declare your test framework in build.sbt!

Sooner or later, you will want to add a few libraries to your project. As it happens, sbt integrates with the Maven (and Ivy) library repository system(s). This means that pulling in most libraries is extremely easy, requiring only a single-line addition to your build.sbt. As an example, suppose that you wanted to add Imgscaler, an image manipulation library, to your build. You can load Maven Central in your browser, search for “imgscalr”, and find that it has a GroupId (organization in sbt-speak) of org.imgscalr, an ArtifactId (name in sbt-speak) of “imgscalr-lib”, and a Latest Version of “4.2″. You would then add this line to your build.sbt:

That’s it! The next time you launch the sbt shell and run compile, Imgscaler will automatically be downloaded for you and included in your build.

One other minor detail you should know is that, if you are adding a dependency on a Scala library, you should use an extra “%” between the organization and the name. For example, if you want to include Spire, the high-performance Scala mathematics library, in your build, you can add this line to your build.sbt:

Note: Multiple libraryDependencies += lines are allowed (Also, you still have to skip lines!).

Of course, we’ve barely scratched the surface of what sbt can do. It really is one of the most powerful build systems, and sbt definitions can get quite complex. I hope this post, however, has made it clear that the sbt can also be one of least-complex build systems. If your needs are simple, your builds will be simple!

You should also check out Chris’ Getting Started with ScalaTest post.

See below for some sbt and Scala resources from Safari Books Online.

Read these titles on Safari Books Online

Not a subscriber? Sign up for a free trial.

Getting Started with SBT for Scala gets you going with using SBT and also introduces its advanced concepts. SBT is a build tool that uses a Scala-based DSL. Additionally, SBT has some interesting features that come in handy during development, such as starting a Scala REPL with project classes and dependencies on the classpath, continuous compilation and testing with triggered execution, and much more.
Developing an Akka Edge walks you through the process of developing a simple Akka-based system, starting from a basic use-case and progressing through a series of enhancements, showing you how you can make a very scalable, efficient and flexible system without a significant amount of work. The key is to understand the essential features Akka provides and then see how you can easily extend your code to make use of them.
Testing in Scala shows you how to create tests with ScalaTest and the Specs2—two of the best testing frameworks available—and how to run your tests in the Simple Build Tool (SBT) designed specifically for Scala projects.

About the author

Chris Hodapp is nearing the completion of a Master’s degree in Computer Science at the University of Alabama, the same school from which he holds an undergraduate CS degree. Since completing two Google Summers of Code with the Scala team, he has spent most of his free time looking for ways to do interesting things both with and to Scala. Chris can be reached on Twitter, where he is @clhodapp.

Tags: Akka, gradle, Homebrew, Ivy, java, Maven, SBT, Scala, Simple Build Tool,

2 Responses to “Hello SBT: An Easy Start with the Simple Build Tool”

  1. David Walend

    Good intro.

    The ” if you are adding a dependency on a Scala library, you should use an extra “%” between the organization and the name.” I don’t quite follow. One % seems to be fine, but two %%s doesn’t work for

    libraryDependencies += “com.assembla.scala-incubator” % “graph-core_2.10″ % “1.7.0″

    Is there some subtlety of meaning needed to be a Scala library other than “written in scala” that I should tell Peter about? Or have I missed a concept?



  2. Chris Hodapp

    Hey David,

    Perhaps I should have been slightly more explicit about what I meant.

    In short if you want to a use a Scala library, it has to have been compiled with the same major version of Scala as the version you are compiling with (In the past, it was even more strict: it had to be with the same minor version). To ensure this, we make the Scala version part of the artifact name in Maven/Ivy. For example, your comment references graph-core 1.7.0, which was built against Scala 2.10.x. The “%%” notation just lets you omit the “version” part of the artifact name. You should use it, though, since it 1) will always pick the right form (X.Y for versions of Scala after 2.10.0, and X.Y.Z for versions before) and 2) prevent you from having to update all of your library dependencies in your build when you move to a new version of Scala in the future.

    So, for your line, I would write:

    libraryDependencies += “com.assembla.scala-incubator” %% “graph-core″ % “1.7.0″

    I hope that helps!