sbt Reference Manual

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Features of sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Getting Started with sbt 25

Installing sbt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Tips and Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Installing sbt on Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Installing from a universal package . . . . . . . . . . . . . . . . . 26

Installing from a third-party package . . . . . . . . . . . . . . . . 26

Installing sbt on Windows . . . . . . . . . . . . . . . . . . . . . . . . . 26

Installing from a universal package . . . . . . . . . . . . . . . . . 26

Windows installer . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Installing sbt on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Installing from a universal package . . . . . . . . . . . . . . . . . 27

Ubuntu and other Debian-based distributions . . . . . . . . . . . 27

Red Hat Enterprise Linux and other RPM-based distributions . . 27

Gentoo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Hello, World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

sbt new command . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Running your app . . . . . . . . . . . . . . . . . . . . . . . . . . 29

1

Exiting sbt shell . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Build definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Base directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

sbt build definition files . . . . . . . . . . . . . . . . . . . . . . . 31

Build support files . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Build products . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Configuring version control . . . . . . . . . . . . . . . . . . . . . 32

Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

sbt shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Batch mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Continuous build and test . . . . . . . . . . . . . . . . . . . . . . 33

Common commands . . . . . . . . . . . . . . . . . . . . . . . . . 33

Tab completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

History Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Build definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Specifying the sbt version . . . . . . . . . . . . . . . . . . . . . . 35

What is a build definition? . . . . . . . . . . . . . . . . . . . . . 35

How build.sbt defines settings . . . . . . . . . . . . . . . . . . . . 36

Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Defining tasks and settings . . . . . . . . . . . . . . . . . . . . . 38

Keys in sbt shell . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Imports in build.sbt . . . . . . . . . . . . . . . . . . . . . . . . . 39

Adding library dependencies . . . . . . . . . . . . . . . . . . . . . 39

Task graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Declaring dependency to other tasks . . . . . . . . . . . . . . . . 41

Inlining .value calls . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Whats the point of the build.sbt DSL? . . . . . . . . . . . . . . 46

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

2

Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

The whole story about keys . . . . . . . . . . . . . . . . . . . . . 48

Scope axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Referring to scopes in a build definition . . . . . . . . . . . . . . 52

Referring to scoped keys from the sbt shell . . . . . . . . . . . . 53

Examples of scoped key notation . . . . . . . . . . . . . . . . . . 53

Inspecting scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

When to specify a scope . . . . . . . . . . . . . . . . . . . . . . . 55

Build-level settings . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Scope delegation . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Appending values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Appending to previous values: += and ++= . . . . . . . . . . . . . 57

Appending with dependencies: += and ++= . . . . . . . . . . . . . 58

Scope delegation (.value lookup) . . . . . . . . . . . . . . . . . . . . . 58

Scope delegation rules . . . . . . . . . . . . . . . . . . . . . . . . 59

Rule 1: Scope axis precedence . . . . . . . . . . . . . . . . . . . . 60

Rule 2: The task axis delegation . . . . . . . . . . . . . . . . . . 60

Rule 3: The configuration axis search path . . . . . . . . . . . . . 61

Rule 4: The subproject axis search path . . . . . . . . . . . . . . 61

Inspect command lists the delegates . . . . . . . . . . . . . . . . 63

.value lookup vs dynamic dispatch . . . . . . . . . . . . . . . . . 64

Library dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Unmanaged dependencies . . . . . . . . . . . . . . . . . . . . . . 67

Managed Dependencies . . . . . . . . . . . . . . . . . . . . . . . 68

Multi-project builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Multiple subprojects . . . . . . . . . . . . . . . . . . . . . . . . . 71

Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Default root project . . . . . . . . . . . . . . . . . . . . . . . . . 74

Navigating projects interactively . . . . . . . . . . . . . . . . . . 74

Common code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Using plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

3

What is a plugin? . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Declaring a plugin . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Enabling and disabling auto plugins . . . . . . . . . . . . . . . . 76

Global plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Available Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Custom settings and tasks . . . . . . . . . . . . . . . . . . . . . . . . . 78

Defining a key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Implementing a task . . . . . . . . . . . . . . . . . . . . . . . . . 79

Execution semantics of tasks . . . . . . . . . . . . . . . . . . . . 80

Turn them into plugins . . . . . . . . . . . . . . . . . . . . . . . . 84

Organizing the build . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

sbt is recursive . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Tracking dependencies in one place . . . . . . . . . . . . . . . . . 85

When to use .scala files . . . . . . . . . . . . . . . . . . . . . . 86

Defining auto plugins . . . . . . . . . . . . . . . . . . . . . . . . . 86

Getting Started summary . . . . . . . . . . . . . . . . . . . . . . . . . 87

sbt: The Core Concepts . . . . . . . . . . . . . . . . . . . . . . . 87

Advanced Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Appendix: Bare .sbt build definition . . . . . . . . . . . . . . . . . . . 88

What is a bare .sbt build definition . . . . . . . . . . . . . . . . . 88

(Pre 0.13.7) Settings must be separated by blank lines . . . . . . 88

Appendix: .scala build definition . . . . . . . . . . . . . . . . . . . . . 88

Relating build.sbt to Build.scala . . . . . . . . . . . . . . . . . . 89

The build definition project in interactive mode . . . . . . . . . . 91

Reminder: its all immutable . . . . . . . . . . . . . . . . . . . . 91

General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Community Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

sbt Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Community Ivy Repository . . . . . . . . . . . . . . . . . . . . . 93

Available Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

4

Test plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Community Repository Policy . . . . . . . . . . . . . . . . . . . . . . . 103

Bintray For Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Create an Open Source Distribution account on Bintray . . . . . 104

Create a repository for your sbt plugins . . . . . . . . . . . . . . 104

Add the sbt-bintray plugin to your build. . . . . . . . . . . . . . 105

Make a release . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Linking your package to the sbt organization . . . . . . . . . . . 106

Linking you