Introduction

This page describes how to use sbt once you have set up your project (see Setup).

Running

Run sbt in your project directory. If you have created a script to start sbt, this should be as simple as:

$ sbt

This starts sbt in interactive mode. You are given a simple prompt at which you type actions (or tasks, targets, phases, or whatever you'd like to call them). There is tab completion and history available at this prompt.

Alternatively, you can run sbt in batch mode. You specify a space-separated list of actions as arguments. For commands that take arguments, pass the command and arguments as one argument to sbt by enclosing them in quotes. For example,

$ sbt clean compile "get sbt.version"

You can make an action run when one or more source files changes by prefixing the action with ~. For example:

> ~ compile

See TriggeredExecution for details.

You can run an action for multiple versions of Scala by prefixing the action with +. See CrossBuild for details.

Actions

Build Actions

• clean

Deletes all generated files (the target directory).

• clean-cache

Deletes the cache of downloaded artifacts and metadata for automatically managed dependencies for this user.

• clean-lib

Deletes the managed library directory for this project.

• compile

Compiles the main sources (in the src/main/scala directory).

• console

Starts the Scala interpreter with a classpath including the compiled sources and all jars in the lib directory. To return to sbt, type :quit, Ctrl+D (Unix), or Ctrl+Z (Windows). Runs test-compile first.

• console-quick

Starts the Scala interpreter with the project classes on the classpath without running any other action first.

• doc

Generates API documentation for Scala source files in src/main/scala using scaladoc. Runs compile first.

• doc-test

Generates API documentation for Scala source files in src/test/scala using scaladoc. Runs test-compile first.

• doc-all

Runs doc and doc-test.

• exec (mixin Exec to your project definition to use this action)

Forks the provided arguments as a new process. Examples:

  > exec echo Hi
  > exec find src/main/scala -iname *.scala -exec wc -l {} ;

• graph-src

Produces a graphviz dot file for the dependency graph between main sources in target/graph/sources

• graph-pkg

Produces a graphviz dot file for the dependency graph between main source directories in target/graph/packages

• javap <option>* <class-name>

Runs javap with the given arguments using the runClasspath for the project. Tab completion is provided for main classes generated from the last successful compilation. Examples:

   > javap your.Clazz
   > javap -c scala.List

• test-javap <option>* <class-name>

Runs javap with the given arguments using the testClasspath for the project. Tab completion is provided for test classes generated from the last successful compilation.

• jetty-run (Web Projects only)

Starts the Jetty server and serves this project as a web application on http://localhost:8080 by default. This variant of starting Jetty is intended to be run from the interactive prompt.

• jetty (Web Projects only)

Starts the Jetty server and serves this project as a web application on http://localhost:8080 by default. This variant of jetty-run is intended to be run batch-style (such as sbt jetty), so it waits for a keypress before completing.

• jetty-stop (Web Projects only)

Stops the Jetty server that was started with the jetty-run action.

• package

For a normal project, creates a jar file containing classes compiled from src/main/scala and the files in src/main/resources after running compile first. For a web application project, creates a war file after running compile and prepareWebapp first.

• package-test

Creates a jar file containing classes compiled from src/test/scala and the files in src/test/resources. Runs test-compile first.

• package-docs

Creates a jar file containing API documentation generated from Scala source files in src/main/scala. Runs doc first.

• package-all

Runs all package tasks except package-project.

• package-project:

Creates a zip file containing the entire project, excluding generated files.

• package-src:

Creates a jar file containing all main source files and resources. The packaged paths are relative to src/main/scala and src/main/resources.

• package-test-src:

Creates a jar file containing all test source files and resources. The packaged paths are relative to src/test/scala and src/test/resources.

• release

Compiles, tests, generates documentation, packages, and increments the version.

• run <argument>*

Runs the main class for the project in the same virtual machine as sbt. The main class is passed the arguments provided. Please see RunningProjectCode for details on the use of System.exit and multithreading (including GUIs) in code run by this action. Runs compile first.

• sh <argument>* (mixin Exec for this action)

Invokes the shell (for unix users) with the command: /bin/sh -c <arguments>. For example:

    > sh find src/main/scala -iname *.scala | xargs cat | wc -l

• test

Runs all tests detected during compilation. Runs test-compile first.

• test-failed <test>*

Runs the tests provided as arguments if they have not succeeded (either failed on the previous test run or have not been run yet). * is interpreted as a wildcard in the test name.

• test-quick <test>*

Runs the tests provided as arguments if they have not succeeded (either failed on the previous test run or have not been run yet) or their dependencies changed. * is interpreted as a wildcard in the test name.

• test-only <test>*

Runs the tests provided as arguments. * is interpreted as a wildcard in the test name.

• test-compile

Compiles the test sources (in the src/test/scala directory). Runs compile first.

• update

Resolves and retrieves external dependencies as described in LibraryManagement.

Build Commands

• exit or quit

End the current interactive session or build.

• reload

Reloads the current interactive session. The project definition is recompiled and reloaded. Any change to the Scala or sbt version does not take effect (see reboot).

• reboot

Use this to reload the project after changing the version of Scala or sbt used for building the project.

• help

Displays a help message and lists these interactive actions and their descriptions.

• actions

List all available actions.

• cc

Monitors sources in Scala projects for changes and runs test-compile when changes are detected. Equivalent to ~ test-compile.

• current

Print the current project and logging level.

• info

Set the logging level to info. This is the default logging level.

• debug

Set the logging level to debug. This logging level is more verbose than info, but does not log stack traces for errors.

• trace

Toggles whether stack traces for errors are displayed. They are disabled by default.

• warn

Set the logging level to warn. This logging level only logs warnings and errors.

• error

Set the logging level to error. This logging level only logs errors.

• set property.name property value

If a user property with name property.name exists for the current project, that property is set to value property value (no quotes are required for values with spaces). Otherwise, the system property with name property.name is set to value property value. (See Properties for more on properties)

• get property.name

Shows the value of the property (user or system) with name property.name. (See Properties for more on properties)

• projects

List all available projects (See SubProjects for more on multiple projects).

• project <project name>

Change the current project to the project named <project name>. Further operations will be done on the given project. (See SubProjects for more on multiple projects)

• console-project

Enters an interactive session with the project instance bound to the 'current' variable. See ProjectConsole for more information.