sbt Reference Manual Contents Preface ................................... 16 Install ................................. 16 Getting Started ............................ 16 Features of sbt ............................ 16 Also .................................. 17 Getting Started with sbt 17 Installing sbt ................................ 17 Tips and Notes ............................ 18 Installing sbt on macOS .......................... 18 Install JDK .............................. 18 Installing from a universal package ................. 18 Installing from a third-party package ................ 18 Installing sbt on Windows ......................... 19 Install JDK .............................. 19 Installing from a universal package ................. 19 Windows installer ........................... 19 Installing from a third-party package ................ 19 Installing sbt on Linux ........................... 19 Installing from SDKMAN ...................... 19 Install JDK .............................. 20 Installing from a universal package ................. 20 Ubuntu and other Debian-based distributions ........... 20 Red Hat Enterprise Linux and other RPM-based distributions .. 21 Gentoo ................................. 21 sbt by example ............................... 21 Create a minimum sbt build ..................... 22 Start sbt shell ............................. 22 Exit sbt shell ............................. 22 Compile a project ........................... 22 Recompile on code change ...................... 22 Create a source file .......................... 23 Run a previous command ...................... 23 1 Getting help .............................. 23 Run your app ............................. 24 Set ThisBuild / scalaVersion from sbt shell ............ 24 Save the session to build.sbt ..................... 24 Name your project .......................... 24 Reload the build ........................... 25 Add ScalaTest to libraryDependencies ............... 25 Run tests ............................... 25 Run incremental tests continuously ................. 25 Write a test .............................. 25 Make the test pass .......................... 26 Add a library dependency ...................... 26 Use Scala REPL ........................... 27 Make a subproject .......................... 28 List all subprojects .......................... 29 Compile the subproject ....................... 29 Add ScalaTest to the subproject .................. 29 Broadcast commands ......................... 29 Make hello depend on helloCore ................... 30 Parse JSON using Play JSON .................... 31 Add sbt-native-packager plugin ................... 32 Reload and create a .zip distribution ................ 33 Dockerize your app .......................... 33 Set the version ............................ 34 Switch scalaVersion temporarily ................... 34 Inspect the dist task ......................... 35 Batch mode .............................. 35 sbt new command .......................... 35 Credits ................................. 35 Directory structure ............................. 36 Base directory ............................. 36 Source code .............................. 36 sbt build definition files ....................... 37 Build support files .......................... 37 Build products ............................ 37 Configuring version control ..................... 37 Running ................................... 37 sbt shell ................................ 38 Batch mode .............................. 38 Continuous build and test ...................... 38 Common commands ......................... 39 Tab completion ............................ 40 sbt shell history ............................ 40 Build definition ............................... 41 Specifying the sbt version ...................... 41 What is a build definition? ..................... 41 2 How build.sbt defines settings .................... 42 Keys .................................. 43 Defining tasks and settings ..................... 44 Keys in sbt shell ........................... 44 Imports in build.sbt ......................... 45 Bare .sbt build definition ...................... 45 Adding library dependencies ..................... 45 Multi-project builds ............................ 46 Multiple subprojects ......................... 46 Dependencies ............................. 48 Inter-project dependencies ...................... 49 Default root project ......................... 50 Navigating projects interactively .................. 50 Common code ............................. 50 Appendix: Subproject build definition files ............. 51 Task graph ................................. 51 Terminology .............................. 52 Declaring dependency to other tasks ................ 52 Inlining .value calls .......................... 54 What’s the point of the build.sbt DSL? .............. 57 Summary ............................... 59 Scopes .................................... 59 The whole story about keys ..................... 59 Scope axes ............................... 60 Referring to scopes in a build definition .............. 62 Referring to scoped keys from the sbt shell ............ 63 Examples of scoped key notation in the sbt shell ......... 63 Inspecting scopes ........................... 64 When to specify a scope ....................... 65 Build-level settings .......................... 65 Scope delegation ........................... 66 Appending values .............................. 67 Appending to previous values: += and ++= ............. 67 Appending with dependencies: += and ++= ............. 68 Scope delegation (.value lookup) ..................... 68 Scope delegation rules ........................ 69 Rule 1: Scope axis precedence .................... 69 Rule 2: The task axis delegation .................. 69 Rule 3: The configuration axis search path ............. 70 Rule 4: The subproject axis search path .............. 71 Inspect command lists the delegates ................ 72 .value lookup vs dynamic dispatch ................. 73 Library dependencies ............................ 76 Unmanaged dependencies ...................... 76 Managed Dependencies ....................... 77 Using plugins ................................ 80 3 What is a plugin? ........................... 80 Declaring a plugin .......................... 80 Enabling and disabling auto plugins ................ 81 Global plugins ............................ 82 Available Plugins ........................... 82 Custom settings and tasks ......................... 83 Defining a key ............................. 83 Implementing a task ......................... 83 Execution semantics of tasks .................... 84 Turn them into plugins ........................ 88 Organizing the build ............................ 88 sbt is recursive ............................ 88 Tracking dependencies in one place ................. 89 When to use .scala files ...................... 90 Defining auto plugins ......................... 90 Getting Started summary ......................... 90 sbt: The Core Concepts ....................... 91 Advanced Notes ............................ 91 Frequently Asked Questions ........................ 91 Project Information ......................... 91 Usage ................................. 92 Build definitions ........................... 93 Extending sbt ............................. 94 Errors ................................. 97 Dependency Management ...................... 98 Miscellaneous ............................. 99 General Information ............................ 99 Credits ................................... 99 Community Plugins ............................ 110 sbt Organization ........................... 110 Community Ivy Repository ..................... 110 Cross building plugins from sbt 0.13 ................ 110 Plugins available for sbt 1.0 (including RC-x) ........... 111 Community Repository Policy ....................... 116 Bintray For Plugins ............................ 116 Create an Open Source Distribution account on Bintray ..... 117 Create a repository for your sbt plugins .............. 117 Add the sbt-bintray plugin to your build. ............. 117 Make a release ............................ 118 Linking your package to the sbt organization ........... 118 Linking your package to the sbt organization (sbt org admins) . 119 Publishing your plugin to a private repository ........... 119 Summary ............................... 119 Setup Notes ................................. 119 Do not put sbt-launch.jar on your classpath. .......... 120 Terminal encoding .......................... 120 4 JVM heap, permgen, and stack sizes ................ 120 Boot directory ............................ 120 HTTP/HTTPS/FTP Proxy ..................... 120 Path encoding ............................. 121 Using Sonatype ............................... 121 Sonatype setup ............................ 121 sbt setup ............................... 122 Optional steps ............................ 124 Contributing to sbt ............................. 126 Documentation ............................ 127 Changes ................................... 127 Migrating from sbt 0.13.x ......................... 127 Migrating case class .copy(...) .................. 127 SbtPlugin ............................... 128 sbt version specific source directory ................. 128 Migrating from sbt 0.12 style .................... 129 Migrating from the Build