Settings and Tasks

Reference for sbt settings and tasks including key types, common operations, and usage patterns

sbt uses a key-value model where settings are evaluated once at project load time and tasks are evaluated on demand. This page documents the core settings and tasks available in sbt.

Key Types

sbt defines three main types of keys:

Key Type	Description	Evaluation
SettingKey[T]	Values computed once at project load	Once per session
TaskKey[T]	Executable tasks that may have side effects	On demand
InputKey[T]	Tasks that accept command-line input	On demand with args

Core Build Settings

Project Identity

name · SettingKey[String] · default: "project directory name"

Project name used for artifact publication and display.

name := "my-project"

organization · SettingKey[String]

Organization or group ID for the project.

organization := "com.example"

version · SettingKey[String]

Project version for artifact publication. Default: "0.1.0-SNAPSHOT"

version := "1.0.0"

Scala Configuration

scalaVersion · SettingKey[String]

The version of Scala used for building. This is one of the most important settings.

scalaVersion := "3.3.1"

scalaBinaryVersion · SettingKey[String]

The Scala version substring describing binary compatibility (e.g., “2.13”, “3”). Automatically derived from scalaVersion.

crossScalaVersions · SettingKey[Seq[String]]

The versions of Scala used when cross-building.

crossScalaVersions := Seq("2.13.12", "3.3.1")

scalaOrganization · SettingKey[String]

Organization/group ID of the Scala used in the project. Advanced setting for Scala language clones. Default: "org.scala-lang"

Path Settings

baseDirectory · SettingKey[File]

The base directory for the build, project, configuration, or task depending on scope.

sourceDirectory := baseDirectory.value / "src"

target · SettingKey[File]

Main directory for files generated by the build.

// Default: baseDirectory.value / "target"
target := baseDirectory.value / "output"

sourceDirectory · SettingKey[File]

Default directory containing sources.

Default: baseDirectory.value / "src"

scalaSource · SettingKey[File]

Default Scala source directory.

Default: sourceDirectory.value / "scala"

javaSource · SettingKey[File]

Default Java source directory.

Default: sourceDirectory.value / "java"

resourceDirectory · SettingKey[File]

Default unmanaged resource directory for user-defined resources.

Default: sourceDirectory.value / "resources"

classDirectory · SettingKey[File]

Directory for compiled classes and copied resources.

Default: target.value / "classes"

Core Tasks

Compilation Tasks

compile · TaskKey[CompileAnalysis]

Compiles sources and returns compilation analysis.

sbt compile
sbt Test/compile

clean · TaskKey[Unit]

Deletes files produced by the build, such as generated sources, compiled classes, and task caches.

sbt clean

Interactive Tasks

console · TaskKey[Unit]

Starts the Scala interpreter (REPL) with the project classes on the classpath.

sbt console

consoleQuick · TaskKey[Unit]

Starts the Scala interpreter with the project dependencies on the classpath (without project classes).

sbt consoleQuick

Run Tasks

run · InputKey[Unit]

Runs a main class, passing along arguments provided on the command line.

sbt run
sbt "run arg1 arg2"

runMain · InputKey[Unit]

Runs the main class selected by the first argument, passing the remaining arguments to the main method.

sbt "runMain com.example.Main arg1 arg2"

Test Tasks

test · InputKey[TestResult]

Executes the tests that either failed before, were not run, or whose transitive dependencies changed.

sbt test

testOnly · InputKey[TestResult]

Executes the tests provided as arguments or all tests if no arguments are provided.

sbt "testOnly com.example.MySpec"

testQuick · InputKey[TestResult]

Executes tests that failed in previous runs or whose dependencies changed.

sbt testQuick

Package Tasks

package · TaskKey[File]

Produces the main artifact, such as a binary JAR. Typically an alias for packageBin.

sbt package

packageBin · TaskKey[File]

Produces a main artifact, such as a binary JAR.

sbt packageBin

packageSrc · TaskKey[File]

Produces a source artifact containing sources and resources.

sbt packageSrc

packageDoc · TaskKey[File]

Produces a documentation artifact containing API documentation.

sbt packageDoc

Documentation Tasks

doc · TaskKey[File]

Generates API documentation using Scaladoc.

sbt doc

Compiler Settings

scalacOptions · TaskKey[Seq[String]]

Options for the Scala compiler.

scalacOptions ++= Seq(
  "-deprecation",
  "-feature",
  "-unchecked"
)

javacOptions · TaskKey[Seq[String]]

Options for the Java compiler.

javacOptions ++= Seq("-source", "11", "-target", "11")

maxErrors · SettingKey[Int] · default: "100"

The maximum number of errors, such as compile errors, to list.

maxErrors := 20

Dependency Management Settings

libraryDependencies · SettingKey[Seq[ModuleID]]

Declares managed dependencies.

libraryDependencies ++= Seq(
  "org.typelevel" %% "cats-core" % "2.10.0",
  "org.scalatest" %% "scalatest" % "3.2.17" % Test
)

resolvers · SettingKey[Seq[Resolver]]

Defines additional resolvers for retrieving dependencies.

resolvers += "Sonatype OSS Snapshots" at 
  "https://oss.sonatype.org/content/repositories/snapshots"

Runtime Settings

fork · SettingKey[Boolean] · default: "false"

If true, forks a new JVM when running. If false, runs in the same JVM as the build.

fork := true

javaOptions · TaskKey[Seq[String]]

Options passed to a new JVM when forking.

javaOptions ++= Seq("-Xmx2G", "-Xms512M")

javaHome · SettingKey[Option[File]]

Selects the Java installation used for compiling and forking. If None, uses the Java installation running the build.

javaHome := Some(file("/usr/lib/jvm/java-17"))

Common Patterns

Scoping Keys

Keys can be scoped to different contexts:

// Scope to configuration
Test / sourceDirectory := baseDirectory.value / "test-sources"

// Scope to task
compile / scalacOptions += "-Ylog-classpath"

// Multiple scopes
Test / console / scalacOptions -= "-Ywarn-unused"

Modifying Settings

// Set value
name := "my-project"

// Append to sequence
scalacOptions += "-deprecation"

// Append multiple items
scalacOptions ++= Seq("-feature", "-unchecked")

// Transform existing value
version := (version.value + "-SNAPSHOT")

Use .value to reference the value of another setting or task within a setting/task definition.

Task Dependencies

Tasks automatically track their dependencies:

customTask := {
  val classes = (Compile / compile).value  // Depends on compile
  val cp = (Compile / fullClasspath).value // Depends on classpath
  // Your task logic here
}

Don’t use .value inside conditionals or lambdas - it must be called at the top level of the task body.

See Also

• Configurations - Understanding Compile, Test, and other configurations
• Directory Structure - Standard sbt project layout
• Command Line - Running sbt commands and options