Setup

Introduction

This page describes how to set up your project for use with sbt.

The basic steps are:

Create a script to launch sbt.
Create your project with sbt.
Put libraries in lib and sources in src.
Read RunningSbt for basic usage instructions.
Read BuildConfiguration for further configuration.

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:

java -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword -Xmx512M -jar `dirname $0`/sbt-launch.jar "$@"

Windows

Create a batch file sbt.bat:

set SCRIPT_DIR=%~dp0
java -Xmx512M -jar "%SCRIPT_DIR%sbt-launch.jar" %*

and put the jar in the same directory as the batch file. Put sbt.bat on your path so that you can launch sbt in any directory by typing sbt at the command prompt.

If you are behind a proxy on Windows, add flags to this second line for proxy host, port, and if applicable, username and password:

java -Dhttp.proxyHost=myproxy -Dhttp.proxyPort=8080 -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword -Xmx512M -jar "%SCRIPT_DIR%sbt-launch.jar" %*

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:

  $ echo 'object Hi { def main(args: Array[String]) { println("Hi!") } }' > hw.scala
  $ sbt
  Project does not exist, create new project? (y/N/s) : s
  ...
  > run
  ...
  Hi!

Directory Layout

Sources

Sbt uses the same directory structure as Maven for source files by default (all paths are relative to the project directory):

  src/
    main/
      resources/
         <files to include in main jar here>
      scala/
         <main Scala sources>
      java/
         <main Java sources>
    test/
      resources
         <files to include in test jar here>
      scala/
         <test Scala sources>
      java/
         <test Java sources>

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:

  target/
  lib_managed/
  project/boot/
  project/build/target/
  project/plugins/target/
  project/plugins/lib_managed/
  project/plugins/src_managed/

A .gitignore for an sbt project should contain these entries:

target/
lib_managed/
src_managed/
project/boot/

Next Step

Read Basic Usage for basic sbt usage information.

Summary

Create a launcher script.
Setup your project information and directory structure by running sbt in your project directory.
Put libraries in lib or configure automatic dependency management.
Read RunningSbt for basic usage instructions.
Start with BuildConfiguration for further project configuration.