{{{{Jack.Viers}}}}: January 2012

Saturday, January 28, 2012

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.

name, ThisProject, project id (default+ hash)
organization, ThisProject, <<= name(StringUtilities.normalize)
credentials, Global, Nil
taskTemporaryDirectory, Global, Some system level temporary directory
watchSources, ThisProject, Nil
sourceDirectory, ThisProject, src
scalaSource, ThisProject, sourceDirectory / "scala"
javaSource, ThisProject, sourceDirectory / "java"
compileOrder, Global, CompileOrder.Mixed
javacOptions, Global, Nil
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.

Monday, January 16, 2012

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

In the previous article, I told you about Scala's Simple Build Tool (SBT), how to install and set up a simple Scala project, and how to use SBT to build and run that project. In this article, I'm going to explain what an SBT Setting is, and provide a list of Settings provided by SBT upon installation.

SBT Settings
SBT Setting objects are made up of three parts: Scope, name, and value. They are represented in the SBT api code as SettingKey traits. Settings are typed generically, and written as SettingKey[T]. The SettingKey trait type, T, defines the type of the SettingKey. For example, if the Setting is a String, the type of the SettingKey representing the Setting is String, and the object is written as SettingKey[String]. In practice, you won't see a SettingKey[String], but the example is there for you to realize that when you look at a SettingKey[T], the SettingKey is always typed to type T, where T is some trait, object, or class name, like String.

SBT Scopes
Scopes are objects containing the names and values of keys within a scope, or section, of the project. They give a setting a context to live in. This allows you to have different settings for your test build than in your src build; a subproject within your build than in your main project of your build; or in the compile task than in the documentation task of your build. Scopes are defined by their ScopeAxis. There are three types of ScopeAxis: typed by Project, typed by Task, and typed by Configuration. The built-in configurations are a subset of those provided by Maven Dependency Scopes: Compile, Run, Package, Document, and Test. Project ScopeAxes refer to the current project. Task ScopeAxes refer to a Task. There is also a Global ScopeAxes, which sets the setting for all axes.

SBT Keys
The name and value of a setting are stored in scopes in a value trait called AttributeKey. The attribute key is typed to contain the type of value stored in the value part of the setting, and defined as AttributeKey[T]. So if a Setting has a string value, the AttributeKey type, T, is String and it is written as AttributeKey[String]. The name part of the Setting is the AttributeKey[T].label member of the AttributeKey[T] trait. The value is only available after evaluating the key within the given scope, and is returned by the AttributeKey[T].evaluate method.

Defining Settings
SBT Settings can be defined in a .sbt build definition file, a *.scala source file under the SBT project directory, or in the sbt users' home .sbt definition file, which defines global default settings for all projects built by sbt by a given user. To explicitly define a Setting within a Scope, you use the SettingKey[T].in method. For example, name in Compile := "My CompileName" sets the name AttributeKey[String] in the Compile configuration Scope.

Available Settings
Here's a list of the over 220 Setting/Task/AttributeKeys (SBT SETTINGS), along with their descriptions, sbt command-line alias, and types. It comes directly from the Keys.scala SBT source file. I've sub-sectioned them by purpose, again, coming directly from the source file. Remember, this is just a list of the available settings. To define a full setting, you must give it a scope (project is the default in .sbt build definition files) and a value (like "MyProjectName") that matches the type of the available key.

TL;DR
This list is not intended to be read linearly. Use the following shortcut links to skip to a section when looking for a particular type of SBT setting, its type, and description. An alternative is to use the browser search to look for a particular setting name, type, and description. In the next article, I am going to talk about some of the default settings that come out of the box with SBT.

Logging Settings