SBT in Action Summary Notes

Notes from the book SBT in Action.

Chapter 1

Maven Concepts

Maven has a set of lifecycles:

Lifecycle
    Phases
        Goals (Tasks in Ant)

Maven has the following lifecycles:

• default — build and deployment
• clean — used to clean
• site — used for documentation

Each phase can have a number of goals. Phases are executed in sequence. All previous phases (and goals) are executed if you call some phase. You can assign goals to phases via plugin goals.

SBT Is Better For

• Type safety
• Ease of making new tasks
• Test and development features for incremental builds

SBT Concepts

SBT just has tasks. Tasks can have dependencies with each other. Tasks with no dependency are executed in parallel. Task output can be passed on to the next task.

Settings are values (e.g., project name).

Plugins — if something is a reusable set of tasks done again and again in different projects, we can abstract it as a plugin. This plugin can be used in different projects and can be sourced by the build file of projects.

Chapter 2

Download and add SBT to your path: scala-sbt.org/download

Every project using SBT should have two files:

• project/build.properties — tells which version of SBT to use
• build.sbt — tells which settings are applicable for this project, including library dependencies

Start SBT by typing sbt at the command prompt.

After SBT starts, you can see the help by typing:

> help

This will show all of the help topics:

help                    Displays this help message or prints detailed help on requested commands (run 'help <command>').
about                   Displays basic information about sbt and the build.
tasks                   Lists the tasks defined for the current project.
settings                Lists the settings defined for the current project.
reload                  (Re)loads the project in the current directory
projects                Lists the names of available projects or temporarily adds/removes extra builds to the session.
project                 Displays the current project or changes to the provided `project`.
set [every] <setting>   Evaluates a Setting and applies it to the current project.
session                 Manipulates session settings.  For details, run 'help session'.
inspect [uses|tree|definitions] <key>   Prints the value for 'key', the defining scope, delegates, related definitions, and dependencies.
<log-level>             Sets the logging level to 'log-level'.  Valid levels: debug, info, warn, error
; <command> (; <command>)*   Runs the provided semicolon-separated commands.
~ <command>             Executes the specified command whenever source files change.
last                    Displays output from a previous command or the output from a specific task.
last-grep               Shows lines from the last output for 'key' that match 'pattern'.
export <tasks>+         Executes tasks and displays the equivalent command lines.
exit                    Terminates the build.
--<command>             Schedules a command to run before other commands on startup.
show <key>              Displays the result of evaluating the setting or task associated with 'key'.

To see which tasks are defined for this project:

> tasks

To see which settings are applicable for this project (e.g., scalaVersion):

> settings

To inspect a specific setting:

> name
[info] learn_sbt

> scalaVersion
[info] 2.10.3

Starting the Scala Console

> console

This will start the Scala console where you can run Scala code. To exit the Scala console, type :q.

If you change build.sbt (or Build.scala) you have to reload the settings:

> reload

Running Tests

> test

Continuous Task Execution

Prefix tasks with ~ to run them continuously on each change:

> ~compile

Auto-completion works in SBT:

> test<TAB>

This will show possible options with tasks similar to test.

To run only a particular test:

> testOnly <TESTNAME>

Chapter 8

When SBT reads your project description, it reads the .sbt files in the root directory, the .sbt files in /project, and .scala files in /project. It compiles everything that it finds and this gives you your build definition. SBT then runs this build and creates your artifact (jar or whatever).

Difference Between Dependency and Plugin

A plugin is simply a jar which contains settings or tasks. The jar contains a definition file which SBT reads to work out what settings and tasks are available.

To include a plugin in your build, add the following lines to project/plugins.sbt:

addSbtPlugin("org.scalastyle" %% "scalastyle-sbt-plugin" % "0.4.0")

resolvers += "sonatype-releases" at
  "https://oss.sonatype.org/content/repositories/releases/"

Repositories of plugins and dependencies are different from each other. If you have a repository which contains both plugins and dependencies of your artifact, you’ll need to include it in both project/plugins.sbt and build.sbt.

Version

When SBT resolves the plugin, it appends both the Scala version and the SBT version. But the appended Scala version number is not the Scala version that you’ve declared in build.sbt, but the version of Scala which is used by SBT.

Example: if build.sbt has scalaVersion := "2.9.2" and you are running SBT version 0.13, then the version appended by addSbtPlugin will be 2.10 (not 2.9.2), because SBT 0.13 uses Scala 2.10. Similarly, if you are running SBT version 0.12 and you have scalaVersion := "2.10", then the version appended will be 2.9.

Create Your Own Plugin

Define the code in project/MyPlugin.scala. In build.sbt, declare the plugin and call the plugin defined in project/MyPlugin.scala.

Credentials

To add credentials for a repository, use the file $HOME/.sbt/0.13/credentials.sbt.