RunningSbt  

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 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 change by prefixing the action with ~. For example:

> ~ compile

See TriggeredExecution for details.

Change the logging level and configure how stack traces are displayed using the debug, info, warn, error, and trace commands described in the Build Commands section below.

You can run an action for multiple versions of Scala by prefixing the action with +. See CrossBuild for details. You can temporarily switch to another version of Scala using ++<version>. This version does not have to be listed in your build.scala.versions property, but it does have to be in a repository or be a local Scala version you have defined. You can also include the initial command to run. For example:

> ++2.7.7 console-quick
[info] Building project test 1.0 against Scala 2.7.7
[info]    using TestProject with sbt 0.7.7 and Scala 2.7.7
...
Welcome to Scala version 2.7.7.final (Java HotSpot(TM) Server VM, Java 1.6.0).
...
scala>
...
> ++2.8.1 console-quick
[info] Building project test 1.0 against Scala 2.8.1
[info]    using TestProject with sbt 0.7.7 and Scala 2.7.7
...
Welcome to Scala version 2.8.1 (Java HotSpot(TM) Server VM, Java 1.6.0).
...
scala>

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 ( lib_managed).
  • clean-plugins
  • Deletes retrieved plugins for this project. It should generally be followed by reload. This is useful for developing plugins.
  • compile
  • Compiles the main sources (in the src/main/scala directory).
  • console
  • Starts the Scala interpreter with a classpath including the compiled sources, all jars in the lib directory, and managed libraries. 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, the lib directory, and managed libraries 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 prepare-webapp 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.
  • 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.
  • test-javap
  • Like javap, but for test classes.
  • test-run <argument>*
  • Like run, but for test classes. Runs test-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. If the Scala or sbt version has changed, the requested versions are retrieved and used. The project definition is recompiled and reloaded if it needed.
  • help
  • Displays a help message and lists these interactive actions and their descriptions.
  • actions
  • List all available actions.
  • 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 on | nosbt | off | <integer>
  • Configures stack trace logging, which is 'on' by default. 'nosbt' prints stack traces up to the first sbt frame. An integer gives the number of frames to show per exception.
  • 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.
  • ~ <command>
  • Executes the project specified action or method whenever source files change. See TriggeredExecution for details.
  • < filename
  • Executes the commands in the given file. Each command should be on its own line. Empty lines and lines beginning with '#' are ignored
  • + <command>
  • Executes the project specified action or method for all versions of Scala defined in the build.scala.versions property.
  • ++<version> <command>
  • Temporarily changes the version of Scala building the project and executes the provided command. <command> is optional. The specified version of Scala is used until sbt exits or ++ is run again. <version> does not need to be listed in the build.scala.versions property, but it must be defined in localScala or be available in a repository.
  • ; A ; B
  • Execute A and if it succeeds, run B. Note that the leading semicolon is required.
  • *
  • Processor management commands. See Processors for details.

History Commands

  • !
  • Show history command help.
  • !!
  • Execute the previous command again.
  • !:
  • Show all previous commands.
  • !:n
  • Show the last n commands.
  • !n
  • Execute the command with index n, as shown by the !: command.
  • !-n
  • Execute the nth command before this one.
  • !string
  • Execute the most recent command starting with 'string'
  • !?string
  • Execute the most recent command containing 'string'