Upload
doannhi
View
359
Download
1
Embed Size (px)
Citation preview
sbt Reference Manual
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Features of sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Getting Started with sbt 22
Installing sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Tips and Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Installing sbt on Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Install JDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Installing from a universal package . . . . . . . . . . . . . . . . . 23
Installing from a third-party package . . . . . . . . . . . . . . . . 23
Installing sbt on Windows . . . . . . . . . . . . . . . . . . . . . . . . . 24
Install JDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Installing from a universal package . . . . . . . . . . . . . . . . . 24
Windows installer . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Installing sbt on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Installing from a universal package . . . . . . . . . . . . . . . . . 24
Install JDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Ubuntu and other Debian-based distributions . . . . . . . . . . . 25
Red Hat Enterprise Linux and other RPM-based distributions . . 25
Gentoo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1
sbt by example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Create a minimum sbt build . . . . . . . . . . . . . . . . . . . . . 27
Start sbt shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Exit sbt shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Compile a project . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Recompile on code change . . . . . . . . . . . . . . . . . . . . . . 28
Create a source file . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Run a previous command . . . . . . . . . . . . . . . . . . . . . . 29
Getting help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Run your app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Set ThisBuild / scalaVersion from sbt shell . . . . . . . . . . . . 29
Save the session to build.sbt . . . . . . . . . . . . . . . . . . . . . 30
Name your project . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Reload the build . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Add ScalaTest to libraryDependencies . . . . . . . . . . . . . . . 31
Run tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Run incremental tests continuously . . . . . . . . . . . . . . . . . 31
Write a test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Make the test pass . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Add a library dependency . . . . . . . . . . . . . . . . . . . . . . 32
Use Scala REPL . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Make a subproject . . . . . . . . . . . . . . . . . . . . . . . . . . 33
List all subprojects . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Compile the subproject . . . . . . . . . . . . . . . . . . . . . . . 34
Add ScalaTest to the subproject . . . . . . . . . . . . . . . . . . 34
Broadcast commands . . . . . . . . . . . . . . . . . . . . . . . . . 35
Make hello depend on helloCore . . . . . . . . . . . . . . . . . . . 35
Parse JSON using Play JSON . . . . . . . . . . . . . . . . . . . . 36
Add sbt-native-packager plugin . . . . . . . . . . . . . . . . . . . 38
Create a .zip distribution . . . . . . . . . . . . . . . . . . . . . . 39
Dockerize your app . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2
Set the version . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Switch scalaVersion temporarily . . . . . . . . . . . . . . . . . . . 40
Inspect the dist task . . . . . . . . . . . . . . . . . . . . . . . . . 40
Batch mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
sbt new command . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Base directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
sbt build definition files . . . . . . . . . . . . . . . . . . . . . . . 42
Build support files . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Build products . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configuring version control . . . . . . . . . . . . . . . . . . . . . 43
Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
sbt shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Batch mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Continuous build and test . . . . . . . . . . . . . . . . . . . . . . 44
Common commands . . . . . . . . . . . . . . . . . . . . . . . . . 45
Tab completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
History Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Build definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Specifying the sbt version . . . . . . . . . . . . . . . . . . . . . . 46
What is a build definition? . . . . . . . . . . . . . . . . . . . . . 47
How build.sbt defines settings . . . . . . . . . . . . . . . . . . . . 47
Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Defining tasks and settings . . . . . . . . . . . . . . . . . . . . . 49
Keys in sbt shell . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Imports in build.sbt . . . . . . . . . . . . . . . . . . . . . . . . . 50
Bare .sbt build definition . . . . . . . . . . . . . . . . . . . . . . 51
Adding library dependencies . . . . . . . . . . . . . . . . . . . . . 51
Task graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Declaring dependency to other tasks . . . . . . . . . . . . . . . . 52
Inlining .value calls . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Whats the point of the build.sbt DSL? . . . . . . . . . . . . . . 58
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
The whole story about keys . . . . . . . . . . . . . . . . . . . . . 60
Scope axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Referring to scopes in a build definition . . . . . . . . . . . . . . 63
Referring to scoped keys from the sbt shell . . . . . . . . . . . . 65
Examples of scoped key notation . . . . . . . . . . . . . . . . . . 65
Inspecting scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
When to specify a scope . . . . . . . . . . . . . . . . . . . . . . . 67
Build-level settings . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Scope delegation . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Appending values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Appending to previous values: += and ++= . . . . . . . . . . . . . 69
Appending with dependencies: += and ++= . . . . . . . . . . . . . 70
Scope delegation (.value lookup) . . . . . . . . . . . . . . . . . . . . . 70
Scope delegation rules . . . . . . . . . . . . . . . . . . . . . . . . 71
Rule 1: Scope axis precedence . . . . . . . . . . . . . . . . . . . . 71
Rule 2: The task axis delegation . . . . . . . . . . . . . . . . . . 72
Rule 3: The configuration axis search path . . . . . . . . . . . . . 72
Rule 4: The subproject axis search path . . . . . . . . . . . . . . 73
Inspect command lists the delegates . . . . . . . . . . . . . . . . 75
.value lookup vs dynamic dispatch . . . . . . . . . . . . . . . . . 76
Library dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Unmanaged dependencies . . . . . . . . . . . . . . . . . . . . . . 79
Managed Dependencies . . . . . . . . . . . . . . . . . . . . . . . 80
Multi-project builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Multiple subprojects . . . . . . . . . . . . . . . . . . . . . . . . . 83
4
Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Inter-project dependencies . . . . . . . . . . . . . . . . . . . . . . 86
Default root project . . . . . . . . . . . . . . . . . . . . . . . . . 86
Navigating projects interactively . . . . . . . . . . . . . . . . . . 87
Common code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Using plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
What is a plugin? . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Declaring a plugin . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Enabling and disabling auto plugins . . . . . . . . . . . . . . . . 89
Global plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Available Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Custom settings and tasks . . . . . . . . . . . . . . . . . . . . . . . . . 91
Defining a key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Implementing a task . . . . . . . . . . . . . . . . . . . . . . . . . 92
Execution semantics of tasks . . . . . . . . . . . . . . . . . . . . 92
Turn them into plugins . . . . . . . . . . . . . . . . . . . . . . . . 97
Organizing the build . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
sbt is recursive . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Tracking dependencies in one place . . . . . . . . . . . . . . . . . 98
When to use .scala files . . . . . . . . . . . . . . . . . . . . . . 99
Defining auto plugins . . . . . . . . . . . . . . . . . . . . . . . . . 99
Getting Started summary . . . . . . . . . . . . . . . . . . . . . . . . . 100
sbt: The Core Concepts . . . . . . . . . . . . . . . . . . . . . . . 100
Advanced Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Community Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
sbt Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Community Ivy Repository . . . . . . . . . . . . . . . . . . . . . 112
Cross building plugins from sbt 0.13 . . . . . . . . . . . . . . . . 113
Plugins available for sbt 1.0 (including RC-x) . . . . . . . . . . . 113
5
Community Repository Policy . . . . . . . . . . . . . . . . . . . . . . . 118
Bintray For Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Create an Open Source Distribution account on Bintray . . . . . 118
Create a repository for your sbt plugins . . . . . . . . . . . . . . 118
Add the sbt-bintray plugin to your build. . . . . . . . . . . . . . 119
Make a release . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Linking your package to the sbt organization . . . . . . . . . . . 120
Linking your package to the sbt organization (sbt org admins) . 120
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Setup Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Do not put sbt-launch.jar on your classpath. . . . . . . . . . . 121
Terminal encoding . . . . . . . . . . . . . . . . . . . . . . . . . . 121
JVM heap, permgen, and stack sizes . . . . . . . . . . . . . . . . 121
Boot directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
HTTP/HTTPS/FTP Proxy . . . . . . . . . . . . . . . . . . . . . 122
Using Sonatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Sonatype setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
SBT setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Second - Configure Sonatype integration . . . . . . . . . . . . . . 124
Third - Publish to the staging repository . . . . . . . . . . . . . . 126
Fourth - Integrate with the release process . . . . . . . . . . . . . 127
Contributing to sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Migrating from sbt 0.13.x . . . . . . . . . . . . . . . . . . . . . . . . . 129
Migrating case class .copy(...) . . . . . . . . . . . . . . . . . . 129
sbt version specific source directory . . . . . . . . . . . . . . . . . 129
Migrating to slash syntax . . . . . . . . . . . . . . . . . . . . . . 130
Migrating from sbt 0.12 style . . . . . . . . . . . . . . . . . . . . 131
Migrating from the Build trait . . . . . . . . . . . . . . . . . . . 133
Migrating from Resolver.withDefaultResolvers . . . . . . . . . . . 135
6
sbt 1.1.x releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
sbt 1.1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
sbt 1.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
sbt 1.1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
sbt 1.0.x releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
sbt 1.0.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
sbt 1.0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
sbt 1.0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
sbt 1.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
sbt 1.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Detailed Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Using sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Command Line Reference . . . . . . . . . . . . . . . . . . . . . . . . . 155
Notes on the command line . . . . . . . . . . . . . . . . . . . . . 155
Project-level tasks . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Configuration-level tasks . . . . . . . . . . . . . . . . . . . . . . . 156
General commands . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Commands for managing the build definition . . . . . . . . . . . 158
Command Line Options . . . . . . . . . . . . . . . . . . . . . . . 159
Console Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Accessing settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Evaluating tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Cross-building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Publishing Conventions . . . . . . . . . . . . . . . . . . . . . . . 163
Using Cross-Built Libraries . . . . . . . . . . . . . . . . . . . . . 163
Cross-Building a Project . . . . . . . . . . . . . . . . . . . . . . . 163
Interacting with the Configuration System . . . . . . . . . . . . . . . . 165
Selecting commands, tasks, and settings . . . . . . . . . . . . . . 165
7
Discovering Settings and Tasks . . . . . . . . . . . . . . . . . . . 167
Triggered Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Running Multiple Commands . . . . . . . . . . . . . . . . . . . . 172
Scripts, REPL, and Dependencies . . . . . . . . . . . . . . . . . . . . . 172
Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
sbt Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Language Server Protocol 3.0 . . . . . . . . . . . . . . . . . . . . 175
Server modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Server discovery and authentication . . . . . . . . . . . . . . . . 177
Initialize request . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
textDocument/publishDiagnostics event . . . . . . . . . . . . 179
textDocument/didSave event . . . . . . . . . . . . . . . . . . . . 179
sbt/exec request . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
sbt/setting request . . . . . . . . . . . . . . . . . . . . . . . . . 180
Understanding Incremental Recompilation . . . . . . . . . . . . . . . . 181
sbt heuristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
How to take advantage of sbt heuristics . . . . . . . . . . . . . . 182
Implementation of incremental recompilation . . . . . . . . . . . . . . 183
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Interaction with the Scala compiler . . . . . . . . . . . . . . . . . 185
Name hashing algorithm . . . . . . . . . . . . . . . . . . . . . . . 186
What is included in the interface of a Scala class . . . . . . . . . 193
Bytecode Enhancers . . . . . . . . . . . . . . . . . . . . . . . . . 196
Further references . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Classpaths, sources, and resources . . . . . . . . . . . . . . . . . . . . 198
Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Compiler Plugin Support . . . . . . . . . . . . . . . . . . . . . . . . . 200
8
Continuations Plugin Example . . . . . . . . . . . . . . . . . . . 201
Version-specific Compiler Plugin Example . . . . . . . . . . . . . 201
Configuring Scala . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Automatically managed Scala . . . . . . . . . . . . . . . . . . . . 201
Using Scala from a local directory . . . . . . . . . . . . . . . . . 203
sbts Scala version . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Forking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Enable forking . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Change working directory . . . . . . . . . . . . . . . . . . . . . . 206
Forked JVM options . . . . . . . . . . . . . . . . . . . . . . . . . 206
Java Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Configuring output . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Configuring Input . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Direct Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Global Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Basic global configuration file . . . . . . . . . . . . . . . . . . . . 208
Global Settings using a Global Plugin . . . . . . . . . . . . . . . 208
Java Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Known issues in mixed mode compilation . . . . . . . . . . . . . 210
Ignoring the Scala source directories . . . . . . . . . . . . . . . . 211
Mapping Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Relative to a directory . . . . . . . . . . . . . . . . . . . . . . . . 211
Rebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Flatten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Local Scala . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Macro Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Defining the Project Relationships . . . . . . . . . . . . . . . . . 214
Common Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 216
9
Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Constructing a File . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Path Finders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
File Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Parallel Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Task ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Practical constraints . . . . . . . . . . . . . . . . . . . . . . . . . 222
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Future work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
External Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Running Project Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
sbts Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Additional test configurations . . . . . . . . . . . . . . . . . . . . 235
JUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Dependency Management . . . . . . . . . . . . . . . . . . . . . . . . . 240
Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Selecting default artifacts . . . . . . . . . . . . . . . . . . . . . . 240
Modifying default artifacts . . . . . . . . . . . . . . . . . . . . . . 241
Defining custom artifacts . . . . . . . . . . . . . . . . . . . . . . 242
Publishing .war files . . . . . . . . . . . . . . . . . . . . . . . . . 243
Using dependencies with artifacts . . . . . . . . . . . . . . . . . . 243
Dependency Management Flow . . . . . . . . . . . . . . . . . . . . . . 244
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
10
Caching and Configuration . . . . . . . . . . . . . . . . . . . . . 244
General troubleshooting steps . . . . . . . . . . . . . . . . . . . . 245
Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Library Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Manual Dependency Management . . . . . . . . . . . . . . . . . 246
Automatic Dependency Management . . . . . . . . . . . . . . . . 247
Proxy Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
sbt Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
~/.sbt/repositories . . . . . . . . . . . . . . . . . . . . . . . . 260
Using credentials for the proxy repository . . . . . . . . . . . . . 260
Proxying Ivy Repositories . . . . . . . . . . . . . . . . . . . . . . 261
Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Define the repository . . . . . . . . . . . . . . . . . . . . . . . . . 263
Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Cross-publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Published artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Modifying the generated POM . . . . . . . . . . . . . . . . . . . 264
Publishing Locally . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Skipping Publishing . . . . . . . . . . . . . . . . . . . . . . . . . 266
Resolvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Maven . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Predefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Custom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Update Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Filtering a Report and Getting Artifacts . . . . . . . . . . . . . . 270
Cached resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Dependency as a graph . . . . . . . . . . . . . . . . . . . . . . . 273
11
Cached resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Caveats and known issues . . . . . . . . . . . . . . . . . . . . . . 275
Consolidated resolution . . . . . . . . . . . . . . . . . . . . . . . 276
Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Tasks and Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Defining a Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Getting values from multiple scopes . . . . . . . . . . . . . . . . 282
Advanced Task Operations . . . . . . . . . . . . . . . . . . . . . 285
Dynamic Computations with Def.taskDyn . . . . . . . . . . . . 286
Using Def.sequential . . . . . . . . . . . . . . . . . . . . . . . . . 287
Handling Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Input Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Input Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Basic Input Task Definition . . . . . . . . . . . . . . . . . . . . . 292
Input Task using Parsers . . . . . . . . . . . . . . . . . . . . . . . 293
The InputTask type . . . . . . . . . . . . . . . . . . . . . . . . . 294
Using other input tasks . . . . . . . . . . . . . . . . . . . . . . . 295
Preapplying input . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Get a Task from an InputTask . . . . . . . . . . . . . . . . . . . 297
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
What is a command? . . . . . . . . . . . . . . . . . . . . . . . 298
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Defining a Command . . . . . . . . . . . . . . . . . . . . . . . . . 299
Full Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Parsing and tab completion . . . . . . . . . . . . . . . . . . . . . . . . 302
Basic parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Built-in parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Combining parsers . . . . . . . . . . . . . . . . . . . . . . . . . . 303
12
Transforming results . . . . . . . . . . . . . . . . . . . . . . . . . 304
Controlling tab completion . . . . . . . . . . . . . . . . . . . . . 305
Dependent parsers . . . . . . . . . . . . . . . . . . . . . . . . . . 305
State and actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Command-related data . . . . . . . . . . . . . . . . . . . . . . . . 306
Project-related data . . . . . . . . . . . . . . . . . . . . . . . . . 307
Project data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Classpaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Running tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Using State in a task . . . . . . . . . . . . . . . . . . . . . . . . . 310
Tasks/Settings: Motivation . . . . . . . . . . . . . . . . . . . . . . . . 310
Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Plugins and Best Practices . . . . . . . . . . . . . . . . . . . . . . . . 312
General Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
project/ vs. ~/.sbt/ . . . . . . . . . . . . . . . . . . . . . . . . 312
Local settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
.sbtrc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Generated files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Dont hard code . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Dont mutate files . . . . . . . . . . . . . . . . . . . . . . . . . 314
Use absolute paths . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Parser combinators . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Using an auto plugin . . . . . . . . . . . . . . . . . . . . . . . . . 316
By Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Plugin dependencies . . . . . . . . . . . . . . . . . . . . . . . . . 317
Creating an auto plugin . . . . . . . . . . . . . . . . . . . . . . . 318
Using a library in a build definition example . . . . . . . . . . . . 324
Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Plugins Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Key naming convention: Use prefix . . . . . . . . . . . . . . . . . 326
13
Artifact naming convention . . . . . . . . . . . . . . . . . . . . . 327
(optional) Plugin naming convention . . . . . . . . . . . . . . . . 328
Dont use default package . . . . . . . . . . . . . . . . . . . . . . 328
Get your plugins known . . . . . . . . . . . . . . . . . . . . . . . 328
Reuse existing keys . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Use settings and tasks. Avoid commands. . . . . . . . . . . . . . 329
Provide core feature in a plain old Scala object . . . . . . . . . . 329
Configuration advices . . . . . . . . . . . . . . . . . . . . . . . . 329
Scoping advices . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Setting up Travis CI with sbt . . . . . . . . . . . . . . . . . . . . . . . 334
Set project/build.properties . . . . . . . . . . . . . . . . . . 334
Read the Travis manual . . . . . . . . . . . . . . . . . . . . . . . 334
Basic setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Plugin build setup . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Custom JVM options . . . . . . . . . . . . . . . . . . . . . . . . . 336
Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Build matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Dealing with flaky network or tests . . . . . . . . . . . . . . . . . 339
More things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Sample setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Testing sbt plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
scripted test framework . . . . . . . . . . . . . . . . . . . . . . . 341
step 1: snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
step 2: scripted-plugin . . . . . . . . . . . . . . . . . . . . . . . . 342
step 3: src/sbt-test . . . . . . . . . . . . . . . . . . . . . . . . . . 342
step 4: write a script . . . . . . . . . . . . . . . . . . . . . . . . . 343
step 5: run the script . . . . . . . . . . . . . . . . . . . . . . . . . 344
step 6: custom assertion . . . . . . . . . . . . . . . . . . . . . . . 344
step 7: testing the test . . . . . . . . . . . . . . . . . . . . . . . . 345
step 8: get inspired . . . . . . . . . . . . . . . . . . . . . . . . . . 346
14
sbt new and Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Trying new command . . . . . . . . . . . . . . . . . . . . . . . . 346
Giter8 support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
How to extend sbt new . . . . . . . . . . . . . . . . . . . . . . . . 348
Cross building plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
How to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Classpaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Include a new type of managed artifact on the classpath, such asmar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Get the classpath used for compilation . . . . . . . . . . . . . . . 350
Get the runtime classpath, including the projects compiled classes351
Get the test classpath, including the projects compiled test classes351
Use packaged jars on classpaths instead of class directories . . . . 352
Get all managed jars for a configuration . . . . . . . . . . . . . . 352
Get the files included in a classpath . . . . . . . . . . . . . . . . 352
Get the module and artifact that produced a classpath entry . . 353
Customizing paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Change the default Scala source directory . . . . . . . . . . . . . 353
Change the default Java source directory . . . . . . . . . . . . . . 354
Change the default resource directory . . . . . . . . . . . . . . . 354
Change the default (unmanaged) library directory . . . . . . . . 354
Disable using the projects base directory as a source directory . 355
Add an additional source directory . . . . . . . . . . . . . . . . . 355
Add an additional resource directory . . . . . . . . . . . . . . . . 355
Include/exclude files in the source directory . . . . . . . . . . . . 355
Include/exclude files in the resource directory . . . . . . . . . . . 356
Include only certain (unmanaged) libraries . . . . . . . . . . . . . 356
Generating files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Generate sources . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Generate resources . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Inspect the build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
15
Show or search help for a command, task, or setting . . . . . . . 359
List available tasks . . . . . . . . . . . . . . . . . . . . . . . . . . 360
List available settings . . . . . . . . . . . . . . . . . . . . . . . . 360
Display the description and type of a setting or task . . . . . . . 361
Display the delegation chain of a setting or task . . . . . . . . . . 361
Show the list of projects and builds . . . . . . . . . . . . . . . . . 362
Show the current session (temporary) settings . . . . . . . . . . . 362
Show basic information about sbt and the current build . . . . . 362
Show the value of a setting . . . . . . . . . . . . . . . . . . . . . 362
Show the result of executing a task . . . . . . . . . . . . . . . . . 363
Show the classpath used for compilation or testing . . . . . . . . 363
Show the main classes detected in a project . . . . . . . . . . . . 363
Show the test classes detected in a project . . . . . . . . . . . . . 364
Interactive mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Use tab completion . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Show more tab completion suggestions . . . . . . . . . . . . . . . 365
Modify the default JLine keybindings . . . . . . . . . . . . . . . . 365
Configure the prompt string . . . . . . . . . . . . . . . . . . . . . 365
Use history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Change the location of the interactive history file . . . . . . . . . 366
Use the same history for all projects . . . . . . . . . . . . . . . . 366
Disable interactive history . . . . . . . . . . . . . . . . . . . . . . 366
Run commands before entering interactive mode . . . . . . . . . 367
Configure and use logging . . . . . . . . . . . . . . . . . . . . . . . . . 367
View the logging output of the previously executed command . . 367
View the previous logging output of a specific task . . . . . . . . 368
Show warnings from the previous compilation . . . . . . . . . . . 369
Change the logging level globally . . . . . . . . . . . . . . . . . . 369
Change the logging level for a specific task, configuration, or project370
Configure printing of stack traces . . . . . . . . . . . . . . . . . . 371
Print the output of tests immediately instead of buffering . . . . 371
16
Add a custom logger . . . . . . . . . . . . . . . . . . . . . . . . . 371
Log messages in a task . . . . . . . . . . . . . . . . . . . . . . . . 372
Log messages in a setting . . . . . . . . . . . . . . . . . . . . . . 372
Project metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Set the project name . . . . . . . . . . . . . . . . . . . . . . . . . 372
Set the project version . . . . . . . . . . . . . . . . . . . . . . . . 373
Set the project organization . . . . . . . . . . . . . . . . . . . . . 373
Set the projects homepage and other metadata . . . . . . . . . . 373
Configure packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Use the packaged jar on classpaths instead of class directory . . . 373
Add manifest attributes . . . . . . . . . . . . . . . . . . . . . . . 374
Change the file name of a package . . . . . . . . . . . . . . . . . 374
Modify the contents of the package . . . . . . . . . . . . . . . . . 374
Running commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Pass arguments to a command or task in batch mode . . . . . . . 375
Provide multiple commands to run consecutively . . . . . . . . . 375
Read commands from a file . . . . . . . . . . . . . . . . . . . . . 375
Define an alias for a command or task . . . . . . . . . . . . . . . 375
Quickly evaluate a Scala expression . . . . . . . . . . . . . . . . . 376
Configure and use Scala . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Set the Scala version used for building the project . . . . . . . . 376
Disable the automatic dependency on the Scala library . . . . . . 376
Temporarily switch to a different Scala version . . . . . . . . . . 377
Use a local Scala installation for building a project . . . . . . . . 377
Build a project against multiple Scala versions . . . . . . . . . . 377
Enter the Scala REPL with a projects dependencies on the class-path, but not the compiled project classes . . . . . . . . . 377
Enter the Scala REPL with a projects dependencies and com-piled code on the classpath . . . . . . . . . . . . . . . . . 377
Enter the Scala REPL with plugins and the build definition onthe classpath . . . . . . . . . . . . . . . . . . . . . . . . . 377
17
Define the initial commands evaluated when entering the ScalaREPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Define the commands evaluated when exiting the Scala REPL . . 378
Use the Scala REPL from project code . . . . . . . . . . . . . . . 378
Generate API documentation . . . . . . . . . . . . . . . . . . . . . . . 379
Select javadoc or scaladoc . . . . . . . . . . . . . . . . . . . . . . 379
Set the options used for generating scaladoc independently ofcompilation . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Add options for scaladoc to the compilation options . . . . . . . 379
Set the options used for generating javadoc independently of com-pilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Add options for javadoc to the compilation options . . . . . . . . 380
Enable automatic linking to the external Scaladoc of manageddependencies . . . . . . . . . . . . . . . . . . . . . . . . . 380
Enable manual linking to the external Scaladoc of managed de-pendencies . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Define the location of API documentation for a library . . . . . . 381
Triggered execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Run a command when sources change . . . . . . . . . . . . . . . 381
Run multiple commands when sources change . . . . . . . . . . . 381
Configure the sources that are checked for changes . . . . . . . . 382
Set the time interval between checks for changes to sources . . . 382
Define Custom Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Define a Task that runs tests in specific sub-projects . . . . . . . 382
How to take an action on startup . . . . . . . . . . . . . . . . . . . . . 383
Sequencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Defining a sequential task with Def.sequential . . . . . . . . . . . 384
Defining a dynamic task with Def.taskDyn . . . . . . . . . . . . . 385
Doing something after an input task . . . . . . . . . . . . . . . . 386
Defining a dynamic input task with Def.inputTaskDyn . . . . . . 388
How to sequence using commands . . . . . . . . . . . . . . . . . 389
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
.sbt build examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
18
.sbt build with .scala files example . . . . . . . . . . . . . . . . . . . . 394
project/Resolvers.scala . . . . . . . . . . . . . . . . . . . . . . . . 394
project/Dependencies.scala . . . . . . . . . . . . . . . . . . . . . 394
project/ShellPromptPlugin.scala . . . . . . . . . . . . . . . . . . 395
build.sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Advanced configurations example . . . . . . . . . . . . . . . . . . . . . 397
Advanced command example . . . . . . . . . . . . . . . . . . . . . . . 399
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . 400
Project Information . . . . . . . . . . . . . . . . . . . . . . . . . 400
Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Build definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Extending sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Dependency Management . . . . . . . . . . . . . . . . . . . . . . 408
Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Values and Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Developers Guide (Work in progress) . . . . . . . . . . . . . . . . . . 412
Towards sbt 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Modularization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Module summary . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
sbt Coding Guideline . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
General goal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
Modular design . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
Binary resiliency . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Other public API matters . . . . . . . . . . . . . . . . . . . . . . 417
Style matters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
sbt-datatype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Using the plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
19
Datatype schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Using datatype to retain binary compatibility . . . . . . . . . . . 424
JSON codec generation . . . . . . . . . . . . . . . . . . . . . . . 426
Existing parameters for protocols, records, etc. . . . . . . . . . . 427
Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Syntax summary . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Compiler Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Fetching the most specific sources . . . . . . . . . . . . . . . . . . . . . 430
sbt Launcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Getting Started with the sbt launcher . . . . . . . . . . . . . . . . . . 431
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Sbt Launcher Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 436
Module Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . 436
Classloader Caching and Isolation . . . . . . . . . . . . . . . . . . 437
Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Service Discovery and Isolation . . . . . . . . . . . . . . . . . . . 438
sbt Launcher Configuration . . . . . . . . . . . . . . . . . . . . . . . . 438
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Variable Substitution . . . . . . . . . . . . . . . . . . . . . . . . . 442
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Core Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Introduction to build state . . . . . . . . . . . . . . . . . . . . . . 444
Settings Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 445
Task Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Settings Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
sbt Settings Discussion . . . . . . . . . . . . . . . . . . . . . . . . 450
Setting Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Controlling Initialization . . . . . . . . . . . . . . . . . . . . . . . 454
20
Build Loaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Custom Resolver . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Custom Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Custom Transformer . . . . . . . . . . . . . . . . . . . . . . . . . 459
The BuildDependencies type . . . . . . . . . . . . . . . . . . . . 460
Creating Command Line Applications Using sbt . . . . . . . . . . . . 461
Hello World Example . . . . . . . . . . . . . . . . . . . . . . . . . 461
Nightly Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Archived pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Hello, World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
sbt new command . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Running your app . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Exiting sbt shell . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Build definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Preface
sbt is a build tool for Scala, Java, and more. It requires Java 1.8 or later.
Install
See Installing sbt for the setup instructions.
Getting Started
To get started, please read the Getting Started Guide. You will save yourself alot of time if you have the right understanding of the big picture up-front. Alldocumentation may be found via the table of contents included at the end ofevery page.
Use Stack Overflow for questions. Use the sbt-dev mailing list for discussing sbtdevelopment. Use [@scala_sbt](https://twitter.com/scala_sbt) for questionsand discussions.
21
https://github.com/d40cht/sbt-cppSetup.htmlGetting-Started.htmlhttps://stackoverflow.com/tags/sbthttps://groups.google.com/d/forum/sbt-dev
Features of sbt
Little or no configuration required for simple projects Scala-based build definition that can use the full flexibility of Scala code Accurate incremental recompilation using information extracted from the
compiler Continuous compilation and testing with triggered execution Packages and publishes jars Generates documentation with scaladoc Supports mixed Scala/Java projects Supports testing with ScalaCheck, specs, and ScalaTest. JUnit is sup-
ported by a plugin. Starts the Scala REPL with project classes and dependencies on the class-
path Modularization supported with sub-projects External project support (list a git repository as a dependency!) Parallel task execution, including parallel test execution Library management support: inline declarations, external Ivy or Maven
configuration files, or manual management
Also
This documentation can be forked on GitHub. Feel free to make correctionsand add documentation.
Documentation for 0.13.x has been archived here. This documentation appliesto sbt 1.2.1.
See also the API Documentation, and the index of names and types.
Getting Started with sbt
sbt uses a small number of concepts to support flexible and powerful builddefinitions. There are not that many concepts, but sbt is not exactly like otherbuild systems and there are details you will stumble on if you havent read thedocumentation.
The Getting Started Guide covers the concepts you need to know to create andmaintain an sbt build definition.
It is highly recommended to read the Getting Started Guide!
If you are in a huge hurry, the most important conceptual background can befound in build definition, scopes, and task graph. But we dont promise thatits a good idea to skip the other pages in the guide.
22
Basic-Def.htmlTriggered-Execution.htmlJava-Sources.htmlTesting.htmlMulti-Project.htmlParallel-Execution.htmlLibrary-Dependencies.htmlhttps://github.com/sbt/website/https://www.scala-sbt.org/0.13/docs/index.html../api/index.htmlName-Index.htmlBasic-Def.htmlScopes.htmlTask-Graph.html
Its best to read in order, as later pages in the Getting Started Guide build onconcepts introduced earlier.
Thanks for trying out sbt and have fun!
Installing sbt
To create an sbt project, youll need to take these steps:
Install JDK (We recommend Oracle JDK 8 or OpenJDK 8). Install sbt. Setup a simple hello world project Move on to running to learn how to run sbt. Then move on to .sbt build definition to learn more about build definitions.
Ultimately, the installation of sbt boils down to a launcher JAR and a shellscript, but depending on your platform, we provide several ways to make theprocess less tedious. Head over to the installation steps for Mac, Windows, orLinux.
Tips and Notes
If you have any trouble running sbt, see Setup Notes on terminal encodings,HTTP proxies, and JVM options.
Installing sbt on Mac
Install JDK
Follow the link to install Java SE Development Kit 8.
Installing from a universal package
Download ZIP or TGZ package, and expand it.
Installing from a third-party package
Note: Third-party packages may not provide the latest version.Please make sure to report any issues with these packages to therelevant maintainers.
23
Hello.htmlRunning.htmlBasic-Def.htmlInstalling-sbt-on-Mac.htmlInstalling-sbt-on-Windows.htmlInstalling-sbt-on-Linux.html../docs/Setup-Notes.htmlhttp://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.htmlhttps://piccolo.link/sbt-1.2.1.ziphttps://piccolo.link/sbt-1.2.1.tgz
Homebrew
$ brew install sbt@1
Macports
$ port install sbt
Installing sbt on Windows
Install JDK
Follow the link to install Java SE Development Kit 8.
Installing from a universal package
Download ZIP or TGZ package and expand it.
Windows installer
Download msi installer and install it.
Installing sbt on Linux
Installing from a universal package
Download ZIP or TGZ package and expand it.
Install JDK
You must first install a JDK. We recommend Oracle JDK 8 or OpenJDK 8. Thedetails around the package names differ from one distribution to another.
For example, Ubuntu xenial (16.04LTS) has openjdk-8-jdk.
Redhat family calls it java-1.8.0-openjdk-devel.
24
http://mxcl.github.com/homebrew/http://macports.org/http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.htmlhttps://piccolo.link/sbt-1.2.1.ziphttps://piccolo.link/sbt-1.2.1.tgzhttps://piccolo.link/sbt-1.2.1.msihttps://piccolo.link/sbt-1.2.1.ziphttps://piccolo.link/sbt-1.2.1.tgzhttps://packages.ubuntu.com/hu/xenial/openjdk-8-jdkhttps://apps.fedoraproject.org/packages/java-1.8.0-openjdk-devel
Ubuntu and other Debian-based distributions
DEB package is officially supported by sbt.
Ubuntu and other Debian-based distributions use the DEB format, but usuallyyou dont install your software from a local DEB file. Instead they come withpackage managers both for the command line (e.g. apt-get, aptitude) or witha graphical user interface (e.g. Synaptic). Run the following from the terminalto install sbt (Youll need superuser privileges to do so, hence the sudo).
echo "deb https://dl.bintray.com/sbt/debian /" | sudo tee -a /etc/apt/sources.list.d/sbt.listsudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 2EE0EA64E40A89B84B2DF73499E82A75642AC823sudo apt-get updatesudo apt-get install sbt
Package managers will check a number of configured repositories for packagesto offer for installation. sbt binaries are published to Bintray, and convenientlyBintray provides an APT repository. You just have to add the repository to theplaces your package manager will check.
Once sbt is installed, youll be able to manage the package in aptitude orSynaptic after you updated their package cache. You should also be able to seethe added repository at the bottom of the list in System Settings -> Software& Updates -> Other Software:
Note: Theres been reports about SSL error using Ubuntu: Serveraccess Error: java.lang.RuntimeException: Unexpected error:java.security.InvalidAlgorithmParameterException: the trustAnchorsparameter must be non-empty url=https://repo1.maven.org/maven2/org/scala-sbt/sbt/1.1.0/sbt-1.1.0.pom,which apparently stems from OpenJDK 9 using PKCS12 format for/etc/ssl/certs/java/cacerts cert-bug. According to https://stackoverflow.com/a/50103533/3827 it is fixed in Ubuntu Cosmic (18.10), but Ubuntu BionicLTS (18.04) is still waiting for a release. See the answer for a woraround.
Red Hat Enterprise Linux and other RPM-based distributions
RPM package is officially supported by sbt.
Red Hat Enterprise Linux and other RPM-based distributions use the RPMformat. Run the following from the terminal to install sbt (Youll need superuserprivileges to do so, hence the sudo).
curl https://bintray.com/sbt/rpm/rpm | sudo tee /etc/yum.repos.d/bintray-sbt-rpm.reposudo yum install sbt
25
https://dl.bintray.com/sbt/debian/sbt-1.2.1.debhttps://bugs.launchpad.net/ubuntu/+source/ca-certificates-java/+bug/1739631https://stackoverflow.com/a/50103533/3827https://stackoverflow.com/a/50103533/3827https://dl.bintray.com/sbt/rpm/sbt-1.2.1.rpm
Figure 1: Ubuntu Software & Updates Screenshot
26
sbt binaries are published to Bintray, and conveniently Bintray provides anRPM repository. You just have to add the repository to the places your packagemanager will check.
On Fedora, sbt 0.13.1 available on official repos. If you want to install sbt1.1.6 or above, you may need to uninstall sbt 0.13 (if its install) and indicatethat you want to install the newest version of sbt (i.e. sbt 1.1.6 or above)using bintray-sbt-rpm.repo then.
sudo dnf remove sbt # uninstalling sbt if sbt 0.13 was installed (may not be necessary)sudo dnf --enablerepo=bintray--sbt-rpm install sbt
Note: Please report any issues with these to the sbt-launcher-package project.
Gentoo
The official tree contains ebuilds for sbt. To install the latest available versiondo:
emerge dev-java/sbt
sbt by example
This page assumes youve installed sbt 1.
Lets start with examples rather than explaining how sbt works or why.
Create a minimum sbt build
$ mkdir foo-build$ cd foo-build$ touch build.sbt
Start sbt shell
$ sbt[info] Updated file /tmp/foo-build/project/build.properties: set sbt.version to 1.1.4[info] Loading project definition from /tmp/foo-build/project[info] Loading settings from build.sbt ...[info] Set current project to foo-build (in build file:/tmp/foo-build/)[info] sbt server started at local:///Users/eed3si9n/.sbt/1.0/server/abc4fb6c89985a00fd95/socksbt:foo-build>
27
https://fedora.pkgs.org/28/fedora-i386/sbt-0.13.1-9.fc28.1.noarch.rpm.htmlhttps://github.com/sbt/sbt-launcher-packagehttps://github.com/sbt/sbt-launcher-packageSetup.html
Exit sbt shell
To leave sbt shell, type exit or use Ctrl+D (Unix) or Ctrl+Z (Windows).
sbt:foo-build> exit
Compile a project
As a convention, we will use the sbt:...> or > prompt to mean that were inthe sbt interactive shell.
$ sbtsbt:foo-build> compile
Recompile on code change
Prefixing the compile command (or any other command) with ~ causes thecommand to be automatically re-executed whenever one of the source files withinthe project is modified. For example:
sbt:foo-build> ~compile[success] Total time: 0 s, completed May 6, 2018 3:52:08 PM1. Waiting for source changes... (press enter to interrupt)
Create a source file
Leave the previous command running. From a different shell or in yourfile manager create in the project directory the following nested directories:src/main/scala/example. Then, create Hello.scala in the example directoryusing your favorite editor as follows:
package example
object Hello extends App {println("Hello")
}
This new file should be picked up by the running command:
[info] Compiling 1 Scala source to /tmp/foo-build/target/scala-2.12/classes ...[info] Done compiling.[success] Total time: 2 s, completed May 6, 2018 3:53:42 PM2. Waiting for source changes... (press enter to interrupt)
Press Enter to exit ~compile.
28
Run a previous command
From sbt shell, press up-arrow twice to find the compile command that youexecuted at the beginning.
sbt:foo-build> compile
Getting help
Use the help command to get basic help about the available commands.
sbt:foo-build> help
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 current project or changes to plugins project or returns from it.new Creates a new sbt build.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`.
....
Display the description of a specific task:
sbt:foo-build> help runRuns a main class, passing along arguments provided on the command line.
Run your app
sbt:foo-build> run[info] Packaging /tmp/foo-build/target/scala-2.12/foo-build_2.12-0.1.0-SNAPSHOT.jar ...[info] Done packaging.[info] Running example.HelloHello[success] Total time: 1 s, completed May 6, 2018 4:10:44 PM
Set ThisBuild / scalaVersion from sbt shell
sbt:foo-build> set ThisBuild / scalaVersion := "2.12.6"[info] Defining ThisBuild / scalaVersion
Check the scalaVersion setting:
29
sbt:foo-build> scalaVersion[info] 2.12.6
Save the session to build.sbt
We can save the ad-hoc settings using session save.
sbt:foo-build> session save[info] Reapplying settings...
build.sbt file should now contain:
ThisBuild / scalaVersion := "2.12.6"
Name your project
Using an editor, change build.sbt as follows:
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
lazy val hello = (project in file(".")).settings(name := "Hello"
)
Reload the build
Use the reload command to reload the build. The command causes thebuild.sbt file to be re-read, and its settings applied.
sbt:foo-build> reload[info] Loading project definition from /tmp/foo-build/project[info] Loading settings from build.sbt ...[info] Set current project to Hello (in build file:/tmp/foo-build/)sbt:Hello>
Note that the prompt has now changed to sbt:Hello>.
30
Add ScalaTest to libraryDependencies
Using an editor, change build.sbt as follows:
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
lazy val hello = (project in file(".")).settings(name := "Hello",libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.5" % Test,
)
Use the reload command to reflect the change in build.sbt.
sbt:Hello> reload
Run tests
sbt:Hello> test
Run incremental tests continuously
sbt:Hello> ~testQuick
Write a test
Leaving the previous command running, create a file named src/test/scala/HelloSpec.scalausing an editor:
import org.scalatest._
class HelloSpec extends FunSuite with DiagrammedAssertions {test("Hello should start with H") {assert("hello".startsWith("H"))
}}
~testQuick should pick up the change:
31
2. Waiting for source changes... (press enter to interrupt)[info] Compiling 1 Scala source to /tmp/foo-build/target/scala-2.12/test-classes ...[info] Done compiling.[info] HelloSpec:[info] - Hello should start with H *** FAILED ***[info] assert("hello".startsWith("H"))[info] | | |[info] "hello" false "H" (HelloSpec.scala:5)[info] Run completed in 135 milliseconds.[info] Total number of tests run: 1[info] Suites: completed 1, aborted 0[info] Tests: succeeded 0, failed 1, canceled 0, ignored 0, pending 0[info] *** 1 TEST FAILED ***[error] Failed tests:[error] HelloSpec[error] (Test / testQuick) sbt.TestsFailedException: Tests unsuccessful
Make the test pass
Using an editor, change src/test/scala/HelloSpec.scala to:
import org.scalatest._
class HelloSpec extends FunSuite with DiagrammedAssertions {test("Hello should start with H") {// Hello, as opposed to helloassert("Hello".startsWith("H"))
}}
Confirm that the test passes, then press Enter to exit the continuous test.
Add a library dependency
Using an editor, change build.sbt as follows:
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
lazy val hello = (project in file(".")).settings(name := "Hello",libraryDependencies += "com.eed3si9n" %% "gigahorse-okhttp" % "0.3.1",libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.5" % Test,
)
32
Use Scala REPL
We can find out the current weather in New York.
sbt:Hello> console[info] Starting scala interpreter...Welcome to Scala 2.12.6 (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_171).Type in expressions for evaluation. Or try :help.
scala> :paste// Entering paste mode (ctrl-D to finish)
import gigahorse._, support.okhttp.Gigahorseimport scala.concurrent._, duration._Gigahorse.withHttp(Gigahorse.config) { http =>
val r = Gigahorse.url("https://query.yahooapis.com/v1/public/yql").get.addQueryString("q" -> """select item.condition
from weather.forecast where woeid in (select woeid from geo.places(1) where text='New York, NY')and u='c'""",
"format" -> "json")
val f = http.run(r, Gigahorse.asString)Await.result(f, 10.seconds)
}
// press Ctrl+D
// Exiting paste mode, now interpreting.
import gigahorse._import support.okhttp.Gigahorseimport scala.concurrent._import duration._res0: String = {"query":{"count":1,"created":"2018-05-06T22:49:55Z","lang":"en-US","results":{"channel":{"item":{"condition":{"code":"26","date":"Sun, 06 May 2018 06:00 PM EDT","temp":"16","text":"Cloudy"}}}}}}
scala> :q // to quit
Make a subproject
Change build.sbt as follows:
33
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
lazy val hello = (project in file(".")).settings(name := "Hello",libraryDependencies += "com.eed3si9n" %% "gigahorse-okhttp" % "0.3.1",libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.5" % Test,
)
lazy val helloCore = (project in file("core")).settings(name := "Hello Core",
)
Use the reload command to reflect the change in build.sbt.
List all subprojects
sbt:Hello> projects[info] In file:/tmp/foo-build/[info] * hello[info] helloCore
Compile the subproject
sbt:Hello> helloCore/compile
Add ScalaTest to the subproject
Change build.sbt as follows:
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
val scalaTest = "org.scalatest" %% "scalatest" % "3.0.5"
lazy val hello = (project in file(".")).settings(name := "Hello",libraryDependencies += "com.eed3si9n" %% "gigahorse-okhttp" % "0.3.1",libraryDependencies += scalaTest % Test,
)
34
lazy val helloCore = (project in file("core")).settings(name := "Hello Core",libraryDependencies += scalaTest % Test,
)
Broadcast commands
Set aggregate so that the command sent to hello is broadcast to helloCoretoo:
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
val scalaTest = "org.scalatest" %% "scalatest" % "3.0.5"
lazy val hello = (project in file(".")).aggregate(helloCore).settings(name := "Hello",libraryDependencies += "com.eed3si9n" %% "gigahorse-okhttp" % "0.3.1",libraryDependencies += scalaTest % Test,
)
lazy val helloCore = (project in file("core")).settings(name := "Hello Core",libraryDependencies += scalaTest % Test,
)
After reload, ~testQuick now runs on both subprojects:
sbt:Hello> ~testQuick
Press Enter to exit the continuous test.
Make hello depend on helloCore
Use .dependsOn(...) to a add dependency on other subprojects. Also letsmove the Gigahorse dependency to helloCore.
35
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
val scalaTest = "org.scalatest" %% "scalatest" % "3.0.5"
lazy val hello = (project in file(".")).aggregate(helloCore).dependsOn(helloCore).settings(name := "Hello",libraryDependencies += scalaTest % Test,
)
lazy val helloCore = (project in file("core")).settings(name := "Hello Core",libraryDependencies += "com.eed3si9n" %% "gigahorse-okhttp" % "0.3.1",libraryDependencies += scalaTest % Test,
)
Parse JSON using Play JSON
Lets add Play JSON to helloCore.
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
val scalaTest = "org.scalatest" %% "scalatest" % "3.0.5"val gigahorse = "com.eed3si9n" %% "gigahorse-okhttp" % "0.3.1"val playJson = "com.typesafe.play" %% "play-json" % "2.6.9"
lazy val hello = (project in file(".")).aggregate(helloCore).dependsOn(helloCore).settings(name := "Hello",libraryDependencies += scalaTest % Test,
)
lazy val helloCore = (project in file("core")).settings(name := "Hello Core",libraryDependencies ++= Seq(gigahorse, playJson),libraryDependencies += scalaTest % Test,
)
36
After reload, add core/src/main/scala/example/core/Weather.scala:
package example.core
import gigahorse._, support.okhttp.Gigahorseimport scala.concurrent._import play.api.libs.json._
object Weather {lazy val http = Gigahorse.http(Gigahorse.config)def weather: Future[String] = {
val r = Gigahorse.url("https://query.yahooapis.com/v1/public/yql").get.addQueryString("q" -> """select item.condition
from weather.forecast where woeid in (select woeid from geo.places(1) where text='New York, NY')and u='c'""".stripMargin,
"format" -> "json")
import ExecutionContext.Implicits._for {f Future.failed(sys.error(rawJson))
}}
}
Next, change src/main/scala/example/Hello.scala as follows:
package example
import scala.concurrent._, duration._import core.Weather
object Hello extends App {val w = Await.result(Weather.weather, 10.seconds)println(s"Hello! The weather in New York is $w.")
37
Weather.http.close()}
Lets run the app to see if it worked:
sbt:Hello> run[info] Compiling 1 Scala source to /tmp/foo-build/core/target/scala-2.12/classes ...[info] Done compiling.[info] Compiling 1 Scala source to /tmp/foo-build/target/scala-2.12/classes ...[info] Packaging /tmp/foo-build/core/target/scala-2.12/hello-core_2.12-0.1.0-SNAPSHOT.jar ...[info] Done packaging.[info] Done compiling.[info] Packaging /tmp/foo-build/target/scala-2.12/hello_2.12-0.1.0-SNAPSHOT.jar ...[info] Done packaging.[info] Running example.HelloHello! The weather in New York is mostly cloudy.
Add sbt-native-packager plugin
Using an editor, create project/plugins.sbt:
addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.3.4")
Next change build.sbt as follows to add JavaAppPackaging:
ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
val scalaTest = "org.scalatest" %% "scalatest" % "3.0.5"val gigahorse = "com.eed3si9n" %% "gigahorse-okhttp" % "0.3.1"val playJson = "com.typesafe.play" %% "play-json" % "2.6.9"
lazy val hello = (project in file(".")).aggregate(helloCore).dependsOn(helloCore).enablePlugins(JavaAppPackaging).settings(name := "Hello",libraryDependencies += scalaTest % Test,
)
lazy val helloCore = (project in file("core")).settings(name := "Hello Core",
38
libraryDependencies ++= Seq(gigahorse, playJson),libraryDependencies += scalaTest % Test,
)
Create a .zip distribution
sbt:Hello> dist[info] Wrote /tmp/foo-build/target/scala-2.12/hello_2.12-0.1.0-SNAPSHOT.pom[info] Wrote /tmp/foo-build/core/target/scala-2.12/hello-core_2.12-0.1.0-SNAPSHOT.pom[info] Your package is ready in /tmp/foo-build/target/universal/hello-0.1.0-SNAPSHOT.zip
Heres how you can run the packaged app:
$ /tmp/someother$ cd /tmp/someother$ unzip -o -d /tmp/someother /tmp/foo-build/target/universal/hello-0.1.0-SNAPSHOT.zip$ ./hello-0.1.0-SNAPSHOT/bin/helloHello! The weather in New York is mostly cloudy.
Dockerize your app
sbt:Hello> Docker/publishLocal....[info] Successfully built b6ce1b6ab2c0[info] Successfully tagged hello:0.1.0-SNAPSHOT[info] Built image hello:0.1.0-SNAPSHOT
Heres how to run the Dockerized app:
$ docker run hello:0.1.0-SNAPSHOTHello! The weather in New York is mostly cloudy
Set the version
Change build.sbt as follows:
ThisBuild / version := "0.1.0"ThisBuild / scalaVersion := "2.12.6"ThisBuild / organization := "com.example"
val scalaTest = "org.scalatest" %% "scalatest" % "3.0.5"val gigahorse = "com.eed3si9n" %% "gigahorse-okhttp" % "0.3.1"
39
val playJson = "com.typesafe.play" %% "play-json" % "2.6.9"
lazy val hello = (project in file(".")).aggregate(helloCore).dependsOn(helloCore).enablePlugins(JavaAppPackaging).settings(name := "Hello",libraryDependencies += scalaTest % Test,
)
lazy val helloCore = (project in file("core")).settings(name := "Hello Core",libraryDependencies ++= Seq(gigahorse, playJson),libraryDependencies += scalaTest % Test,
)
Switch scalaVersion temporarily
sbt:Hello> ++2.11.12![info] Forcing Scala version to 2.11.12 on all projects.[info] Reapplying settings...[info] Set current project to Hello (in build file:/tmp/foo-build/)
Check the scalaVersion setting:
sbt:Hello> scalaVersion[info] helloCore / scalaVersion[info] 2.11.12[info] scalaVersion[info] 2.11.12 scalaVersion[info] 2.12.6
This setting will go away after reload.
Inspect the dist task
To find out more about dist, try help and inspect.
sbt:Hello> help distCreates the distribution packages.sbt:Hello> inspect dist
40
To call inspect recursively on the dependency tasks use inspect tree.
sbt:Hello> inspect tree dist[info] dist = Task[java.io.File][info] +-Universal / dist = Task[java.io.File]....
Batch mode
You can also run sbt in batch mode, passing sbt commands directly from theterminal.
$ sbt clean "testOnly HelloSpec"
Note: Running in batch mode requires JVM spinup and JIT each time, so yourbuild will run much slower. For day-to-day coding, we recommend usingthe sbt shell or a continuous test like ~testQuick.
sbt new command
You can use the sbt new command to quickly setup a simple Hello world build.
$ sbt new sbt/scala-seed.g8....A minimal Scala project.
name [My Something Project]: hello
Template applied in ./hello
When prompted for the project name, type hello.
This will create a new project under a directory named hello.
Credits
This page is based on the Essential sbt tutorial written by William ScalaWilliam Narmontas.
Directory structure
This page assumes youve installed sbt and seen the Hello, World example.
41
https://www.scalawilliam.com/essential-sbt/Setup.htmlHello.html
Base directory
In sbts terminology, the base directory is the directory containing the project.So if you created a project hello containing hello/build.sbt as in the Hello,World example, hello is your base directory.
Source code
sbt uses the same directory structure as Maven for source files by default (allpaths are relative to the base directory):
src/main/resources/
scala/
java/
test/resources
scala/
java/
Other directories in src/ will be ignored. Additionally, all hidden directorieswill be ignored.
Source code can be placed in the projects base directory as hello/app.scala,which may be for small projects, though for normal projects people tend to keepthe projects in the src/main/ directory to keep things neat. The fact that youcan place *.scala source code in the base directory might seem like an oddtrick, but this fact becomes relevant later.
sbt build definition files
The build definition is described in build.sbt (actually any files named *.sbt)in the projects base directory.
build.sbt
42
Hello.htmlHello.htmlhttps://maven.apache.org/Organizing-Build.html
Build support files
In addition to build.sbt, project directory can contain .scala files that de-fines helper objects and one-off plugins. See organizing the build for more.
build.sbtproject/Dependencies.scala
You may see .sbt files inside project/ but they are not equivalent to .sbt filesin the projects base directory. Explaining this will come later, since youll needsome background information first.
Build products
Generated files (compiled classes, packaged jars, managed files, caches, anddocumentation) will be written to the target directory by default.
Configuring version control
Your .gitignore (or equivalent for other version control systems) should con-tain:
target/
Note that this deliberately has a trailing / (to match only directories) and itdeliberately has no leading / (to match project/target/ in addition to plaintarget/).
Running
This page describes how to use sbt once you have set up your project. It assumesyouve installed sbt and created a Hello, World or other project.
sbt shell
Run sbt in your project directory with no arguments:
$ sbt
43
Organizing-Build.htmlOrganizing-Build.htmlSetup.htmlHello.html
Running sbt with no command line arguments starts sbt shell. sbt shell has acommand prompt (with tab completion and history!).
For example, you could type compile at the sbt shell:
> compile
To compile again, press up arrow and then enter.
To run your program, type run.
To leave sbt shell, type exit or use Ctrl+D (Unix) or Ctrl+Z (Windows).
Batch mode
You can also run sbt in batch mode, specifying a space-separated list of sbtcommands as arguments. For sbt commands that take arguments, pass thecommand and arguments as one argument to sbt by enclosing them in quotes.For example,
$ sbt clean compile "testOnly TestA TestB"
In this example, testOnly has arguments, TestA and TestB. The commandswill be run in sequence (clean, compile, then testOnly).
Note: Running in batch mode requires JVM spinup and JIT each time, so yourbuild will run much slower. For day-to-day coding, we recommend usingthe sbt shell or Continuous build and test feature described below.
Beginning in sbt 0.13.16, using batch mode in sbt will issue an informationalstartup message,
$ sbt clean compile[info] Executing in batch mode. For better performance use sbt's shell...
It will only be triggered for sbt compile, and it can also be supressed withsuppressSbtShellNotification := true.
Continuous build and test
To speed up your edit-compile-test cycle, you can ask sbt to automatically re-compile or run tests whenever you save a source file.
Make a command run when one or more source files change by prefixing thecommand with ~. For example, in sbt shell try:
44
> ~testQuick
Press enter to stop watching for changes.You can use the ~ prefix with either sbt shell or batch mode.See Triggered Execution for more details.
Common commands
Here are some of the most common sbt commands. For a more complete list,see Command Line Reference.cleanDeletes all generated files (in the target directory).compileCompiles the main sources (in src/main/scala and src/main/java directories).testCompiles and runs all tests.consoleStarts the Scala interpreter with a classpath including the compiled sourcesand all dependencies. To return to sbt, type :quit, Ctrl+D (Unix), or Ctrl+Z(Windows).run *Runs the main class for the project in the same virtual machine as sbt.packageCreates a jar file containing the files in src/main/resources and the classes com-piled from src/main/scala and src/main/java.help Displays detailed help for the specified command. If no command is provided,displays brief descriptions of all commands.reloadReloads the build definition (build.sbt, project/.scala, project/.sbt files). Neededif you change the build definition.
Tab completion
sbt shell has tab completion, including at an empty prompt. A special sbtconvention is that pressing tab once may show only a subset of most likelycompletions, while pressing it more times shows more verbose choices.
45
Triggered-Execution.htmlCommand-Line-Reference.html
History Commands
sbt shell remembers history, even if you exit sbt and restart it. The simplestway to access history is with the up arrow key. The following commands arealso supported:
!
Show history command help.
!!
Execute the previous command again.
!:
Show all previous commands.
!:n
Show the last n commands.
!n
Execute the command with index n, as shown by the !: command.
!-n
Execute the nth command before this one.
!string
Execute the most recent command starting with string.
!?string
Execute the most recent command containing string.
Build definition
This page describes sbt build definitions, including some theory and the syntaxof build.sbt. It assumes you have installed a recent version of sbt, such as sbt1.2.1, know how to use sbt, and have read the previous pages in the GettingStarted Guide.
This page discusses the build.sbt build definition.
Specifying the sbt version
As part of your build definition you will specify the version of sbt that yourbuild uses. This allows people with different versions of the sbt launcher tobuild the same projects with consistent results. To do this, create a file namedproject/build.properties that specifies the sbt version as follows:
46
Running.html
sbt.version=1.2.1
If the required version is not available locally, the sbt launcher will downloadit for you. If this file is not present, the sbt launcher will choose an arbitraryversion, which is discouraged because it makes your build non-portable.
What is a build definition?
A build definition is defined in build.sbt, and it consists of a set of projects(of type Project). Because the term project can be ambiguous, we often call ita subproject in this guide.For instance, in build.sbt you define the subproject located in the currentdirectory like this:
lazy val root = (project in file(".")).settings(name := "Hello",scalaVersion := "2.12.6"
)
Each subproject is configured by key-value pairs.For example, one key is name and it maps to a string value, the name of yoursubproject. The key-value pairs are listed under the .settings(...) methodas follows:
lazy val root = (project in file(".")).settings(name := "Hello",scalaVersion := "2.12.6"
)
How build.sbt defines settings
build.sbt defines subprojects, which holds a sequence of key-value pairs calledsetting expressions using build.sbt DSL.
lazy val root = (project in file(".")).settings(name := "hello",organization := "com.example",scalaVersion := "2.12.6",version := "0.1.0-SNAPSHOT"
)
47
../api/sbt/Project.html
Lets take a closer look at the build.sbtDSL:Each entry is called a setting expression. Some among them are also called taskexpressions. We will see more on the difference later in this page.A setting expression consists of three parts:
1. Left-hand side is a key.2. Operator, which in this case is :=3. Right-hand side is called the body, or the setting body.
On the left-hand side, name, version, and scalaVersion are keys. A key isan instance of SettingKey[T], TaskKey[T], or InputKey[T] where T is theexpected value type. The kinds of key are explained below.Because key name is typed to SettingKey[String], the := operator on nameis also typed specifically to String. If you use the wrong value type, the builddefinition will not compile:
lazy val root = (project in file(".")).settings(name := 42 // will not compile
)
build.sbt may also be interspersed with vals, lazy vals, and defs. Top-levelobjects and classes are not allowed in build.sbt. Those should go in theproject/ directory as Scala source files.
Keys
Types There are three flavors of key:
SettingKey[T]: a key for a value computed once (the value is computedwhen loading the subproject, and kept around).
TaskKey[T]: a key for a value, called a task, that has to be recomputedeach time, potentially with side effects.
InputKey[T]: a key for a task that has command line arguments as input.Check out Input Tasks for more details.
48
../api/sbt/SettingKey.html../api/sbt/TaskKey.html../api/sbt/InputKey.htmlInput-Tasks.html
Built-in Keys The built-in keys are just fields in an object called Keys. Abuild.sbt implicitly has an import sbt.Keys._, so sbt.Keys.name can bereferred to as name.
Custom Keys Custom keys may be defined with their respective creationmethods: settingKey, taskKey, and inputKey. Each method expects the typeof the value associated with the key as well as a description. The name of thekey is taken from the val the key is assigned to. For example, to define a keyfor a new task called hello,
lazy val hello = taskKey[Unit]("An example task")
Here we have used the fact that an .sbt file can contain vals and defs inaddition to settings. All such definitions are evaluated before settings regardlessof where they are defined in the file.
Note: Typically, lazy vals are used instead of vals to avoid initial-ization order problems.
Task vs Setting keys A TaskKey[T] is said to define a task. Tasks areoperations such as compile or package. They may return Unit (Unit is Scalafor void), or they may return a value related to the task, for example packageis a TaskKey[File] and its value is the jar file it creates.
Each time you start a task execution, for example by typing compile at theinteractive sbt prompt, sbt will re-run any tasks involved exactly once.
sbts key-value pairs describing the subproject can keep around a fixed stringvalue for a setting such as name, but it has to keep around some executable codefor a task such as compile even if that executable code eventually returns astring, it has to be re-run every time.
A given key always refers to either a task or a plain setting. That is, taskiness(whether to re-run each time) is a property of the key, not the value.
Defining tasks and settings
Using :=, you can assign a value to a setting and a computation to a task. Fora setting, the value will be computed once at project load time. For a task, thecomputation will be re-run each time the task is executed.
For example, to implement the hello task from the previous section:
49
../api/sbt/Keys\protect \char "0024\relax .html
lazy val hello = taskKey[Unit]("An example task")
lazy val root = (project in file(".")).settings(hello := { println("Hello!") }
)
We already saw an example of defining settings when we defined the projectsname,
lazy val root = (project in file(".")).settings(name := "hello"
)
Types for tasks and settings From a type-system perspective, the