Launching Sbt

The easiest way to launch sbt is to create a one-line script. Download sbt-launch.jar if you have not already.

Note: do not put sbt-launch.jar in your $SCALA_HOME/lib directory, your project's lib directory, or anywhere it will be put on a classpath.

Note: The encoding used by your terminal may differ from Java's default encoding for your platform. In this case, you will need to add the option -Dfile.encoding=<encoding> in the following scripts to set the encoding.

Unix

Put the jar in your ~/bin directory, put the line

java -Xmx512M -jar `dirname $0`/sbt-launch.jar "$@"

in a file called sbt in your ~/bin directory and do

$ chmod u+x ~/bin/sbt

This allows you to launch sbt in any directory by typing sbt at the command prompt.

sbt will pick up any HTTP proxy settings from the http.proxy environment variable. If you are behind a proxy requiring authentication, you must in addition pass flags to set the http.proxyUser and http.proxyPassword properties:

Create Project

Full Setup

When you run sbt and it does not find a project in the current directory, it asks if you want to create a new project. If you say yes, sbt will prompt for some basic information:

Project name: This name will be used in scaladocs and as part of the default name for generated packages.

Project organization: This is used for dependency management and is optional.

Project version: This is used in scaladocs, as part of the default name for generated packages, and for dependency management.

Scala version: This is version(s) of scala to build the project with. Multiple versions may be separated by spaces (see CrossBuild). Allowed values are (in theory) any version of Scala 2.7.2 or later available in the Scala Tools repository.

Sbt version: This is the version of sbt to build the project with. Currently, this should be 0.7.0, 0.7.1, 0.7.2, 0.7.3, 0.7.4, 0.7.5, or 0.7.7.

See Loader for more information on setting the versions of Scala and sbt to use to build your project. With the above information, sbt creates the project properties file and directory structure. These are described in the following section.

Quick Setup

In addition to 'yes' or 'no', you can type s (for scratch) when prompted to create a new project. This can be used to quickly get sbt compiling and running code without needing to do a full project setup. This option skips all of the prompts in a full setup and configures sbt to look in the current directory for sources and jars in addition to the usual places in a full project. Using sbt for a hello world might look like:

Other directories in src/ will be ignored. Additionally, all hidden directories will be ignored.

Dependencies

All dependencies (jars) go in the

lib/

directory or any subdirectory of lib. Again, hidden directories will be ignored. If you want to use ScalaCheck, specs, or ScalaTest for testing, those jars should go in here as well. Alternatively, you can configure sbt to automatically manage your dependencies (see LibraryManagement).

Build Configuration

Build configuration is done in the project directory:

project/
build.properties
build/
boot/

The build.properties file contains the project name, version, and organization, the versions of Scala and sbt used to build the project, and any other user-defined properties (see Properties). You can directly edit this file to change these properties or you can use the set command at the interactive prompt (see Basic Usage). The build directory is where further configuration is done and is described in BuildConfiguration. The boot directory is where the versions of Scala and sbt used to build the project are downloaded to.

Products

Generated files (classes, jars, analysis, and documentation) will be written to the

target/

directory. Automatically managed dependencies are downloaded to:

lib_managed/

Version Control

sbt creates and uses several directories that you will normally want to exclude from version control: