sbt — The Interactive Build Tool for Scala and Java

Introduction

sbt (originally Simple Build Tool) is the default build tool for the Scala ecosystem. It provides incremental compilation that recompiles only what changed, an interactive shell for rapid feedback during development, and deep integration with the Scala compiler. While primarily used for Scala, sbt also handles Java and mixed Scala/Java projects, making it the standard choice for JVM teams working with Scala.

What sbt Does

• Compiles Scala and Java sources incrementally, recompiling only affected files on each change
• Manages library dependencies via Apache Ivy and Maven Central repositories
• Provides an interactive REPL-like shell for running build tasks without restart overhead
• Supports multi-project builds for monorepos with inter-project dependencies
• Runs tests in parallel with framework support for ScalaTest, MUnit, and Specs2

Architecture Overview

sbt uses a task-graph execution model where build definitions are composed of settings and tasks that form a directed acyclic graph. The build definition is written in Scala (in build.sbt), making it fully type-checked. Zinc, the incremental compiler, analyzes source dependencies at the method signature level to determine the minimal set of files to recompile. The interactive shell keeps the JVM warm between commands, avoiding repeated startup costs. Dependency resolution uses Coursier, a fast artifact fetcher that downloads and caches JARs from Maven and Ivy repositories in parallel.

Self-Hosting & Configuration

• Install via Homebrew (brew install sbt), SDKMAN (sdk install sbt), or download from the official site
• Define project metadata and dependencies in build.sbt at the project root
• Place Scala sources in src/main/scala/ and tests in src/test/scala/ following Maven conventions
• Add plugins in project/plugins.sbt for code formatting, assembly, Docker packaging, and more
• Configure the JVM with .sbtopts or JAVA_OPTS for memory tuning on large projects

Key Features

• Zinc incremental compiler provides sub-second recompilation for most edits
• Interactive shell with tab completion and watch mode (~) for continuous compilation
• Coursier-based dependency resolution downloads artifacts in parallel with local caching
• Multi-project builds let you structure monorepos with shared libraries and independent apps
• Extensive plugin ecosystem covers code formatting (scalafmt), Docker builds (sbt-native-packager), and release automation

Comparison with Similar Tools

• Gradle — general-purpose JVM build tool with Groovy/Kotlin DSL; sbt offers deeper Scala compiler integration
• Maven — XML-based, convention-over-configuration; sbt uses Scala for build definitions with type safety
• Mill — newer Scala build tool with simpler semantics; sbt has a larger ecosystem and community
• Bazel — polyglot build system focused on hermeticity; sbt is simpler to set up for Scala-only projects
• Pants — monorepo build system; sbt handles multi-project Scala builds with less infrastructure

FAQ

Q: Is sbt only for Scala? A: No. sbt compiles Java sources alongside Scala and can manage pure Java projects, though Gradle or Maven are more common for Java-only codebases.

Q: How do I speed up sbt on large projects? A: Use sbt's built-in server mode to keep the JVM running between sessions, increase heap size with -Xmx, and enable Coursier's parallel downloads.

Q: What is the difference between build.sbt and project/*.scala? A: build.sbt uses a simplified syntax for settings. Files in project/ are full Scala code that defines plugins and custom build logic, forming a recursive build definition.

Q: Can sbt produce Docker images? A: Yes. The sbt-native-packager plugin generates Docker images, RPM/DEB packages, and universal zip archives from your project.

Sources

• https://github.com/sbt/sbt
• https://www.scala-sbt.org/1.x/docs/