sbt Reference Manual - sbt - The interactive build tool · sbt Reference Manual ... 1. sbtbyexample...

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


Windows installer . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Installing sbt on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . 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.


Download ZIP or TGZ package and expand it.

Windows installer

Download msi installer and install it.

Installing sbt on Linux


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



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



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


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



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:



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



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.


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:


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


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

sbt Reference Manual - sbt - The interactive build tool · sbt Reference Manual ... 1. sbtbyexample...

Documents

Transcript of sbt Reference Manual - sbt - The interactive build tool · sbt Reference Manual ... 1. sbtbyexample...