SBT ~ Scala's Simple Build Tool Series, Part 3. SBT Default Settings

In the previous article, I explained what an SBT Setting is, and provided a list of Settings provided by SBT upon installation. In this article, I am going to describe some of the defaults provided by SBT out of the box.

SBT Default Settings and Scopes.
SBT's Default Settings are defined in the Defaults.scala source file. There are two configuration scopes where settings are defined, the GlobalScope configuration scope, and the ThisProject configuration scope (the project to be built, that is, YOUR project). Settings cascade, that is, each ScopeAxis (Global, Project, Configuration, or Task), falls back on another ScopeAxis if a setting is requested from it that was not defined in the scope of the task. In this way, SBT build definitions, which are sequences of initialized settings, are similar to Cascading Style Sheets, with lower-level ScopeAxis, like Task Scopes, overriding the settings of the ScopeAxis that they extend from (using the extend method).


At the top level, is the GlobalScope. You could use this scope to define things like yourself as an author or contributor, add the ENSIME plugin to all your projects, etc. All other scope definitions come from this Global root. In Defaults.scala, this is used to set defaults for many of the 220+ keys available in SBT. A consequence of this is that if you do not set a setting to what you want, SBT will set it to a default setting for you. An example, the name settingKey. Fire up SBT inside an empty project and don't create a name entry in the .sbt build definition file. Type inspect name at the prompt. You'll get something like the following:


> inspect name
[info] Setting: java.lang.String = default-42f6d6
[info] Description:
[info] Project name.
[info] Provided by:
[info] {file:/Users/jackviers/Library/Developer/sbtProj/}default-42f6d6/*:name
[info] Dependencies:
[info] *:this-project
[info] Reverse dependencies:
[info] *:project-info
[info] *:normalized-name
[info] *:on-load-message
[info] *:description
[info] Delegates:
[info] *:name
[info] {.}/*:name
[info] */*:name

Fig. 1. Result of not setting name in build using sbt.

Note that the name setting is a Setting[String] with the value of default-42f6d6. This is a great feature. It means that for your average build, you don't need to know a ton of SBT settings, because SBT will fill them in for you. It also means that, if you wish, you may override or add to existing SBT settings at almost any level of your build.

Important SBT Default Settings

The following is a list of prevalent default settings, with their ScopeAxis defaults where provided. You can find them in the SBT source code, mostly in the Defaults.scala file, or by starting sbt in interactive mode and using the inspect command.

1. name, ThisProject, project id (default+ hash)
2. organization, ThisProject, <<= name(StringUtilities.normalize)
3. credentials, Global, Nil
4. taskTemporaryDirectory, Global, Some system level temporary directory
5. watchSources, ThisProject, Nil
6. sourceDirectory, ThisProject, src
7. scalaSource, ThisProject, sourceDirectory / "scala"
8. javaSource, ThisProject, sourceDirectory / "java"
9. compileOrder, Global, CompileOrder.Mixed
10. javacOptions, Global, Nil
11. scalacOptions, Global, Nil

Again, you can override any of the 220+ settings however you would like, but SBT, in most cases, will define them for you.

In the next article I will discuss the various tasks available out of the box with SBT.