>
>
❦
Contents
sbt Reference Manual
Install
Getting Started
Features of sbt
Also
Getting Started with sbt
Installing sbt
Tips and Notes
Installing sbt on Mac
Installing from a third-party package
Macports
Homebrew
Installing from a universal package
Typesafe Activator
Installing manually
Installing sbt on Windows
Windows installer
Installing from a universal package
Typesafe Activator
Installing manually
Installing sbt on Linux
Installing from a universal package
Ubuntu and other Debian-based distributions
Red Hat Enterprise Linux and other RPM-based distributions
Gentoo
Typesafe Activator
Installing manually
Installing sbt manually
Unix
Windows
Non-Cygwin
Cygwin with the standard Windows termnial
Cygwin with an Ansi terminal
Installing Typesafe Activator (including sbt)
Hello, World
Create a project directory with source code
Build definition
Setting the sbt version
Directory structure
Base directory
Source code
sbt build definition files
Build products
Configuring version control
Running
Interactive mode
Batch mode
Continuous build and test
Common commands
Tab completion
History Commands
.sbt build definition
Three Flavors of Build Definition
What is a Build Definition?
How build.sbt defines settings
Keys
Types
Built-in Keys
Custom Keys
Task vs Setting keys
Defining tasks and settings
Types for tasks and settings
Keys in sbt interactive mode
Imports in build.sbt
Adding library dependencies
Scopes
The whole story about keys
Scope axes
Scoping by project axis
Scoping by configuration axis
Scoping by task axis
Global scope
Delegation
Referring to scoped keys when running sbt
Examples of scoped key notation
Inspecting scopes
Referring to scopes in a build definition
When to specify a scope
More kinds of setting
Refresher: Settings
Appending to previous values: += and ++=
Computing a value based on other keys values
Settings with dependencies
When settings are undefined
Tasks based on other keys values
Tasks with dependencies
Appending with dependencies: += and ++=
Library dependencies
Unmanaged dependencies
Managed Dependencies
The libraryDependencies key
Getting the right Scala version with %%
Ivy revisions
Resolvers
Overriding default resolvers
Per-configuration dependencies
Multi-project builds
Multiple projects
Common settings
Dependencies
Aggregation
Classpath dependencies
Per-configuration classpath dependencies
Default root project
Navigating projects interactively
Common code
Using plugins
What is a plugin?
Declaring a plugin
Enabling and disabling auto plugins
Global plugins
Available Plugins
Custom settings and tasks
Defining a key
Implementing a task
Execution semantics of tasks
Deduplication of task dependencies
Cleanup task
Use plain Scala
Turn them into plugins
Organizing the build
sbt is recursive
Tracking dependencies in one place
When to use .scala files
Defining auto plugins
Getting Started summary
sbt: The Core Concepts
Advanced Notes
Appendix: Bare .sbt build definition
What is a bare .sbt build definition
(Pre 0.13.7) Settings must be separated by blank lines
Appendix: .scala build definition
Relating build.sbt to Build.scala
The build definition project in interactive mode
Reminder: it s all immutable
General Information
Credits
Community Plugins
sbt Organization
Community Ivy Repository
Available Plugins
Plugins for IDEs
Test plugins
Code coverage plugins
Static code analysis plugins
One jar plugins
Release plugins
Deployment integration plugins
Monitoring integration plugins
Web and frontend development plugins
Documentation plugins
Library dependency plugins
Build interoperability plugins
Create new project plugins
Utility and system plugins
Database plugins
Code generator plugins
Game development plugins
Android plugins
iOS plugins
OSGi plugin
C++ interop plugins
Computer vision plugins
Plugin bundles
Community Repository Policy
Bintray For Plugins
Create an account on Bintray
Create a repository for your sbt plugins
Add the bintray-sbt plugin to your build.
Make a release
Linking your package to the sbt organization
Linking your package to the sbt organization (sbt org admins)
Summary
Setup Notes
Do not put sbt-launch.jar on your classpath.
Terminal encoding
JVM heap, permgen, and stack sizes
Boot directory
HTTP/HTTPS/FTP Proxy
Deploying to Sonatype
First - PGP Signatures
Second - Maven Publishing Settings
Third - POM Metadata
Fourth - Adding credentials
Finally - Publish
Summary
~/.sbt/sonatype.sbt
~/.sbt/plugins/gpg.sbt
build.sbt
Contributing to sbt
Documentation
Changes
sbt 0.13.5+ Technology Previews
sbt 0.13.11
Fixes with compatibility implications
Improvements
Bug fixes
Configurable Scala compiler bridge
Dotty awareness
Inter-project dependency tracking
Def.settings
sbt 0.13.10
sbt 0.13.9
Fixes with compatibility implications
Improvements
Bug fixes
crossScalaVersions default value
POM files no longer include certain source and javadoc jars
retrieveManaged related improvements
Cached resolution fixes
Force GC
Maven compatibility fix
sbt 0.13.8
Changes with compatibility implications
Improvements
Fixes
Rolling back XML parsing workaround
Cross-version support for Scala sources
Maven resolver plugin
Project-level dependency exclusions
Sequential tasks
Nicer ways of declaring project settings
Bytecode Enhancers
sbt 0.13.7
Fixes with compatibility implications
Improvements
Bug fixes
Natural whitespace handling
Custom Maven local repository location
Circular dependency
Cached resolution (minigraph caching)
sbt 0.13.6
Fixes with compatibility implications
Improvements
Bug fixes
HTTPS related changes
enablePlugins/disablePlugins
Unresolved dependencies error
Eviction warnings
Latest SNAPSHOTs
Consolidated resolution
sbt 0.13.5
sbt 0.13.0 - 0.13.2
sbt 0.13.2
sbt 0.13.1
sbt 0.13.0
Features, fixes, changes with compatibility implications
Features
Fixes
Improvements
Other
Details of major changes
camelCase Key names
New key definition methods
New task/setting syntax
.sbt format enhancements
Control over automatically added settings
Resolving Scala dependencies
sbt 0.12.4
sbt 0.12.3
sbt 0.12.2
sbt 0.12.1
Dependency management fixes:
Three stage incremental compilation:
Miscellaneous fixes and improvements:
Forward-compatible-only change (not present in 0.12.0):
sbt 0.12.0
Features, fixes, changes with compatibility implications
Features
Fixes
Improvements
Experimental or In-progress
Details of major changes from 0.11.2 to 0.12.0
Plugin configuration directory
Parsing task axis
Aggregation
Parallel Execution
Source dependencies
Cross building
Global repository setting
test-quick
Argument quoting
scala-library.jar
Older Changes
0.11.3 to 0.12.0
0.11.2 to 0.11.3
0.11.1 to 0.11.2
0.11.0 to 0.11.1
0.10.1 to 0.11.0
0.10.0 to 0.10.1
0.7.7 to 0.10.0
0.7.5 to 0.7.7
0.7.4 to 0.7.5
0.7.3 to 0.7.4
0.7.2 to 0.7.3
0.7.1 to 0.7.2
0.7.0 to 0.7.1
0.5.6 to 0.7.0
0.5.5 to 0.5.6
0.5.4 to 0.5.5
0.5.2 to 0.5.4
0.5.1 to 0.5.2
0.4.6 to 0.5/0.5.1
0.4.5 to 0.4.6
0.4.3 to 0.4.5
0.4 to 0.4.3
0.3.7 to 0.4
0.3.6 to 0.3.7
0.3.5 to 0.3.6
0.3.2 to 0.3.5
0.3.1 to 0.3.2
0.3 to 0.3.1
0.2.3 to 0.3
0.2.2 to 0.2.3
0.2.1 to 0.2.2
0.2.0 to 0.2.1
0.1.9 to 0.2.0
0.1.8 to 0.1.9
0.1.7 to 0.1.8
0.1.6 to 0.1.7
0.1.5 to 0.1.6
0.1.4 to 0.1.5
0.1.3 to 0.1.4
0.1.2 to 0.1.3
0.1.1 to 0.1.2
0.1 to 0.1.1
Migrating from 0.7 to 0.10+
Why move to 0.13.11?
Step 1: Read the Getting Started Guide for sbt 0.13.11
Step 2: Install sbt 0.13.11
Step 3: A technique for switching an existing project
Preserve project/ for 0.7.x project
Create build.sbt for 0.13.11
Run sbt 0.13.11
Switching back to sbt 0.7.x
FAQs
Detailed Topics
Using sbt
Command Line Reference
Notes on the command line
Project-level tasks
Configuration-level tasks
General commands
Commands for managing the build definition
Command Line Options
Console Project
Description
Accessing settings
Examples
Evaluating tasks
Examples
State
Examples
Cross-building
Introduction
Publishing Conventions
Using Cross-Built Libraries
Cross-Building a Project
Interacting with the Configuration System
Selecting commands, tasks, and settings
Selecting the configuration
Task-specific Settings
Discovering Settings and Tasks
Value and Provided By
Related Settings
Dependencies
Requested Dependencies
Actual Dependencies
Delegates
Triggered Execution
Compile
Testing
Running Multiple Commands
Scripts, REPL, and Dependencies
Setup
Setup with Conscript
Manual Setup
Usage
sbt Script runner
Example
sbt REPL with dependencies
Example:
Understanding Incremental Recompilation
sbt heuristics
How to take advantage of sbt heuristics
Configuration
Classpaths, sources, and resources
Basics
Unmanaged vs managed
Excluding source files by name
External vs internal
Keys
Example
Compiler Plugin Support
Continuations Plugin Example
Version-specific Compiler Plugin Example
Configuring Scala
Automatically managed Scala
Configuring the scala-library dependency
Configuring additional Scala dependencies
Configuring Scala tool dependencies
Switching to a local Scala version
Using Scala from a local directory
Mixing with managed dependencies
Using unmanaged dependencies only
sbt s Scala version
Forking
Enable forking
Change working directory
Forked JVM options
Java Home
Configuring output
Configuring Input
Direct Usage
Global Settings
Basic global configuration file
Global Settings using a Global Plugin
Java Sources
Usage
Known issues in mixed mode compilation
Ignoring the Scala source directories
Mapping Files
Relative to a directory
Rebase
Flatten
Alternatives
Local Scala
Macro Projects
Introduction
Defining the Project Relationships
Common Interface
Distribution
Paths
Constructing a File
Path Finders
Selecting descendants
get
Selecting children
Existing files only
Name Filter
Combining PathFinders
Filtering
Empty PathFinder
PathFinder to String conversions
Mappings
File Filters
Parallel Execution
Task ordering
Practical constraints
Background
Configuration
Tagging Tasks
Defining Restrictions
Built-in Tags and Rules
Custom Tags
Future work
Tagging Tasks
Fractional weighting
Default Behavior
Adjustments to Defaults
Other characteristics
External Processes
Usage
Examples
Running Project Code
Problems
System.exit
Threads
Deserialization and class loading
sbt s Solutions
System.exit
Threads
User Code
Testing
Basics
testOnly
testQuick
Tab completion
Other tasks
Output
Test Reports
Options
Test Framework Arguments
Setup and Cleanup
Disable Parallel Execution of Tests
Filter classes
Forking tests
Additional test configurations
Integration Tests
Custom test configuration
Additional test configurations with shared sources
Application to parallel execution
JUnit
Extensions
Custom Test Framework
Custom Test Reporters
Using Extensions
Dependency Management
Artifacts
Selecting default artifacts
Modifying default artifacts
Defining custom artifacts
Publishing .war files
Using dependencies with artifacts
Dependency Management Flow
Background
Caching and Configuration
General troubleshooting steps
Plugins
Notes
Library Management
Introduction
Manual Dependency Management
Automatic Dependency Management
Inline Declarations
Dependencies
Resolvers
Override default resolvers
Override all resolvers for all builds
Explicit URL
Disable Transitivity
Classifiers
Exclude Transitive Dependencies
Download Sources
Extra Attributes
Inline Ivy XML
Ivy Home Directory
Checksums
Conflict Management
Eviction warning
Overriding a version
Unresolved dependencies error
Cached resolution
Publishing
Configurations
External Maven or Ivy
Ivy settings (resolver configuration)
Ivy file (dependency configuration)
Maven pom (dependencies only)
Full Ivy Example
Forcing a revision (Not recommended)
Known limitations
Proxy Repositories
Overview
sbt Configuration
~/.sbt/repositories
Launcher Script
sbt.override.build.repos
sbt.repository.config
Proxying Ivy Repositories
Publishing
Define the repository
Credentials
Cross-publishing
Published artifacts
Modifying the generated POM
Publishing Locally
Resolvers
Maven
Predefined
Custom
Basic Examples
Filesystem
URL
SFTP and SSH Repositories
Custom Layout
Update Report
Filtering a Report and Getting Artifacts
Filter Basics
ConfigurationFilter
ModuleFilter
ArtifactFilter
DependencyFilter
Cached resolution
Setup
Dependency as a graph
Cached resolution
Caveats and known issues
First runs
Ivy fidelity is not guaranteed
SNAPSHOT and dynamic dependencies
Motivation
Tasks and Commands
Tasks
Introduction
Features
Defining a Task
Hello World example (sbt)
Define the key
Implement the task
Defining a basic task
Tasks with inputs
Task Scope
On precedence
Separating implementations
Modifying an Existing Task
Getting values from multiple scopes
Introduction
Example
ScopeFilter
Unspecified filters
More on filter construction
Combining ScopeFilters
More operations
Missing values
Multiple values from multiple scopes
Advanced Task Operations
Streams: Per-task logging
Dynamic Computations with Def.taskDyn
Using Def.sequential
Handling Failure
failure
result
andFinally
Input Tasks
Input Keys
Basic Input Task Definition
Input Task using Parsers
Constructing the Parser
Constructing the Task
The InputTask type
Using other input tasks
Preapplying input
Get a Task from an InputTask
Commands
What is a command ?
Introduction
Defining a Command
General commands
No-argument commands
Single-argument command
Multi-argument command
Full Example
Parsing and tab completion
Basic parsers
Built-in parsers
Combining parsers
Transforming results
Controlling tab completion
State and actions
Command-related data
Project-related data
Project data
Classpaths
Running tasks
Using State in a task
Tasks/Settings: Motivation
Application
Plugins and Best Practices
General Best Practices
project/ vs. ~/.sbt/
Local settings
.sbtrc
Generated files
Don t hard code
Don t mutate files
Use absolute paths
Parser combinators
Plugins
Using an auto plugin
By Description
Plugin dependencies
Global plugins
Creating an auto plugin
projectSettings and buildSettings
Implementing plugin dependencies
Root plugins and triggered plugins
Controlling the import with autoImport
Example Plugin
Usage example
Global plugins example
Using a library in a build definition example
1a) Manually managed
1b) Automatically managed: direct editing approach
1c) Automatically managed: command-line approach
1d) Project dependency
2) Use the library
Best Practices
Plugins Best Practices
Get your plugins known
Don t use default package
Follow the naming conventions
Use settings and tasks. Avoid commands.
Use sbt.AutoPlugin
Reuse existing keys
Avoid namespace clashes
Provide core feature in a plain old Scala object
Configuration advices
You probably won t need your own configuration
When to define your own configuration
Playing nice with configurations
Provide raw settings and configured settings
Using a main task scope for settings
Mucking with globalSettings
Setting up Travis CI with sbt
Set project/build.properties
Read the Travis manual
Basic setup
Plugin build setup
Custom JVM options
(Experimental) Reusing Ivy cache
Build matrix
Notification
Dealing with flaky network or tests
More things
Sample setting
How to…
Classpaths
Include a new type of managed artifact on the classpath, such as mar
Get the classpath used for compilation
Get the runtime classpath, including the project s compiled classes
Get the test classpath, including the project s compiled test classes
Use packaged jars on classpaths instead of class directories
Get all managed jars for a configuration
Get the files included in a classpath
Get the module and artifact that produced a classpath entry
Customizing paths
Change the default Scala source directory
Change the default Java source directory
Change the default resource directory
Change the default (unmanaged) library directory
Disable using the project s base directory as a source directory
Add an additional source directory
Add an additional resource directory
Include/exclude files in the source directory
Include/exclude files in the resource directory
Include only certain (unmanaged) libraries
Generating files
Generate sources
Generate resources
Inspect the build
Show or search help for a command, task, or setting
List available tasks
List available settings
Display tree of setting/task dependencies
Display the description and type of a setting or task
Display the delegation chain of a setting or task
Display related settings or tasks
Show the list of projects and builds
Show the current session (temporary) settings
Show basic information about sbt and the current build
Show the value of a setting
Show the result of executing a task
Show the classpath used for compilation or testing
Show the main classes detected in a project
Show the test classes detected in a project
Interactive mode
Use tab completion
Show more tab completion suggestions
Modify the default JLine keybindings
Configure the prompt string
Use history
Change the location of the interactive history file
Use the same history for all projects
Disable interactive history
Run commands before entering interactive mode
Configure and use logging
View the logging output of the previously executed command
View the previous logging output of a specific task
Show warnings from the previous compilation
Change the logging level globally
Change the logging level for a specific task, configuration, or project
Configure printing of stack traces
Print the output of tests immediately instead of buffering
Add a custom logger
Log messages in a task
Project metadata
Set the project name
Set the project version
Set the project organization
Set the project s homepage and other metadata
Configure packaging
Use the packaged jar on classpaths instead of class directory
Add manifest attributes
Change the file name of a package
Modify the contents of the package
Running commands
Pass arguments to a command or task in batch mode
Provide multiple commands to run consecutively
Read commands from a file
Define an alias for a command or task
Quickly evaluate a Scala expression
Configure and use Scala
Set the Scala version used for building the project
Disable the automatic dependency on the Scala library
Temporarily switch to a different Scala version
Use a local Scala installation for building a project
Build a project against multiple Scala versions
Enter the Scala REPL with a project s dependencies on the classpath, but not the compiled project classes
Enter the Scala REPL with a project s dependencies and compiled code on the classpath
Enter the Scala REPL with plugins and the build definition on the classpath
Define the initial commands evaluated when entering the Scala REPL
Define the commands evaluated when exiting the Scala REPL
Use the Scala REPL from project code
Generate API documentation
Select javadoc or scaladoc
Set the options used for generating scaladoc independently of compilation
Add options for scaladoc to the compilation options
Set the options used for generating javadoc independently of compilation
Add options for javadoc to the compilation options
Enable automatic linking to the external Scaladoc of managed dependencies
Enable manual linking to the external Scaladoc of managed dependencies
Define the location of API documentation for a library
Triggered execution
Run a command when sources change
Run multiple commands when sources change
Configure the sources that are checked for changes
Set the time interval between checks for changes to sources
Define Custom Tasks
Define a Task that runs tests in specific sub-projects
Sequencing
Defining a sequential task with Def.sequential
project/build.properties
project/style.sbt
build.sbt
Defining a dynamic task with Def.taskDyn
project/build.properties
project/style.sbt
build.sbt v1
build.sbt v2
Doing something after an input task
src/main/scala/Greeting.scala
build.sbt v1
build.sbt v2
Defining a dynamic input task with Def.inputTaskDyn
build.sbt v1
build.sbt v2
How to sequence using commands
Examples
.sbt build examples
.sbt build with .scala files example
project/Resolvers.scala
project/Dependencies.scala
project/ShellPrompPlugin.scala
build.sbt
Advanced configurations example
Advanced command example
Frequently Asked Questions
Project Information
How do I get help?
How do I report a bug?
How can I help?
Usage
My last command didn t work but I can t see an explanation. Why?
How do I disable ansi codes in the output?
How can I start a Scala interpreter (REPL) with sbt project configuration (dependencies, etc.)?
Build definitions
What are the := , += , and ++= methods?
What is the % method?
What is ModuleID , Project , ?
How do I add files to a jar package?
How can I generate source code or resources?
How can a task avoid redoing work if the input files are unchanged?
Extending sbt
How can I add a new configuration?
How do I add a test configuration?
How can I create a custom run task, in addition to run ?
How should I express a dependency on an outside tool such as proguard?
How would I change sbt s classpath dynamically?
Example of dynamic classpath augmentation
How can I take action when the project is loaded or unloaded?
Example of project load/unload hooks
Errors
On project load, Reference to uninitialized setting
Dependency Management
How do I resolve a checksum error?
I ve added a plugin, and now my cross-compilations fail!
Miscellaneous
How do I use the Scala interpreter in my code?
0.7 to 0.10+ Migration
How do I migrate from 0.7 to 0.10+?
Where has 0.7 s lib_managed gone?
What are the commands I can use in 0.13.11 vs. 0.7?
Why have the resolved dependencies in a multi-module project changed since 0.7?
My tests all run really fast but some are broken that weren t in 0.7!
What happened to the web development and Web Start support since 0.7?
How are inter-project dependencies different in 0.13.11 vs. 0.7?
Where did class/object X go since 0.7?
Where can I find plugins for 0.13.11?
Index
Values and Types
Dependency Management
Settings and Tasks
Process
Build Structure
Methods
Settings and Tasks
File and IO
Dependency Management
Parsing
Processes
Developer’s Guide (Work in progress)
Towards sbt 1.0
Concepts
Source compatibility of the build deinition
Binary compatibility of the plugins
Modularization
Module summary
IO API ( sbt/io )
Serialization API ( sbt/serialization )
Util APIs ( sbt/util )
LibraryManagement API ( sbt/librarymanagement )
IncrementalCompiler API ( sbt/incrementalcompiler )
Build API (tbd)
sbt Launcher ( sbt/launcher )
Client/Server (tbd)
Website ( sbt/website )
sbt Coding Guideline
General goal
Clean up old deprecation
Aim for zero warnings (except deprecation)
Modular design
Aim small
Public APIs should be coded against interfaces
Hide implementation details
Depend less
Hide external classes
Hide internal modules
Compiler flags
Package name and organization name
Binary resiliency
MiMa
Public traits should contain def declarations only
Abstract classes are also useful
Seal the traits and abstract classes
Finalize the leaf classes
Typeclass and subclass inheritance
Avoid case classes, use sbt-datatype
Prefer method overloading over default parameter values
Other public API matter
Avoid Stringly-typed programming
Avoid overuse of def apply
Use specific datatype ( Vector , List , or Array ) rather than Seq .
Avoid calling toSeq or anything side-effecty on Set
Avoid calling toSeq on Map
Avoid functions and tuples in the signature, if Java interop is needed
Style matter
Use scalariform
Avoid procedure syntax
Typeclass instances are encouraged to be defined in the companions
Implicit converter for syntax (enrich-my-library) should be imported
Datatype
Using the plugin
Types generated
Protocols
Example:
Records
Example:
Enumerations
Example:
Existing parameters for protocols, records, etc.
Using datatype to retain binary compatibility
Syntax summary
Compiler Interface
Fetching the most specific sources
sbt Launcher
Getting Started with the sbt launcher
Overview
Applications
Servers
Resolving Applications/Servers
Creating a Launched Application
Running an Application
Execution
Sbt Launcher Architecture
Module Resolution
Classloader Caching and Isolation
Caching
Locking
Service Discovery and Isolation
Sbt Launcher Configuration
Example
1. Scala Configuration
2. Application Identification
3. Repositories Section
4. The Boot section
5. The Ivy section
6. The Server Section
Variable Substitution
Syntax
Notes
Core Principles
Introduction to build state
Settings Architecture
Task Architecture
Settings Core
Example
Setting up
Example Settings System
Example Usage
sbt Settings Discussion
Scopes
Constructing settings
Settings definitions
Setting Initialization
Controlling Initialization
Build Loaders
Custom Resolver
API Documentation
Full Example
Custom Builder
API Documentation
Example
Custom Transformer
API Documentation
Manipulating Project Dependencies in Settings
The BuildDependencies type
Example
Creating Command Line Applications Using sbt
Hello World Example
Build Definition: build.sbt
Application: Main.scala
Launcher configuration file: hello.build.properties
Nightly Builds
Contents in Depth
Combined Pages
Documentation
Download
Get Involved
