sbt has moved

sbt has now completely moved to GitHub.

See https://github.com/harrah/xsbt/wiki/Settings.

Introduction

This page describes build configuration for when the default actions or paths are not sufficient or appropriate for your project.

• sbt has moved
• Introduction
• Example
• Configuration Details
• Specifying Options
• Compile Options
• Run Options
• Package Options
• Document Options
• Test Options
• Changing Paths

Example

sbt is configured by creating a project definition in the project/build directory. A project definition is a class (written in Scala) that implements sbt.Project. This is usually done by extending sbt.DefaultProject. The following is an example of adding a Hello World task to your build. It assumes you have already initialized your project as described on the Setup page.

project/build/HelloWorld.scala

import sbt._

class HelloWorldProject(info: ProjectInfo) extends DefaultProject(info)
{
  lazy val hi = task { println("Hello World"); None }
}

If you have sbt running, you need to reload the project with the new project definition:

> reload

Otherwise, start up sbt. Execute hi:

> hi
...
Hello World
...

The details of writing tasks are described on the Creating/Modifying Actions page.

Configuration Details

sbt only recompiles a project definition on startup or when invoking the interactive command reload. Therefore, if you are running in interactive mode, invoke reload after making changes to your project definition for the changes to take effect.

The project/build directory is a project itself. Therefore, you can add jars to the project/build/lib directory to use from your project definition. You can also use multiple sources for your project definition. The only requirement is there must be exactly one public, concrete subclass of Project with a constructor that accepts a ProjectInfo instance. sbt finds this subclass when it compiles the project definition, so the names of source files and classes are not important.

Specifying Options

The general way to configure your build is to override one or more methods in your project definition. For example, the default options for the compile task are defined in the compileOptions method:

    def compileOptions: Seq[CompileOption] = Deprecation :: Nil

Deprecation is a val in ScalaProject that is an instance of CompileOption and represents the command line scalac option -deprecation. To additionally specify the -unchecked command line option, override compileOptions in your project definition (class TestProject above):

    override def compileOptions = super.compileOptions ++ Seq(Unchecked)

The currently available options for tasks are listed below.

Compile Options

Method compileOptions specifies additional options for task compile to pass to the Scala compiler. It has type Seq[CompileOption]. There is a similar method testCompileOptions for test-compile. Provided options are:

• Deprecation
• Unchecked
• ExplainTypes
• Optimize
• Verbose
• DisableWarnings
• target(t: Target.Value) (accepts values of the Target enumeration: Java1_5, Java1_4, Msil)
• MaxCompileErrors(max: Int) Specifies the maximum number of compiler errors to show. The default value is 100.
• compileOptions(options: String*) (for arbitrary options). Example:

  override def compileOptions = super.compileOptions ++
     compileOptions("-encoding", "utf8")

Method javaCompileOptions specifies the options passed to the Java compiler by the compile task. There is a similar method testJavaCompileOptions for test-compile. Currently, all options are specified by:

• javaCompileOptions(option: String*)

Run Options

Method mainClass is of type Option[String] and specifies an optional main class to run when the run task is invoked. The default implementation specifies no main class (None). When mainClass is not specified, the run task will determine which class to run automatically. If exactly one main class is detected, it is run. If multiple main classes are detected, the user is prompted for which one to run.

Package Options

If defined, the mainClass method specifies the value of the Main-Class attribute in the manifest. The manifestClassPathmethod, if defined, specifies the value of Class-Path attribute. Method packageOptions specifies general options for task package and is of type Seq[PackageOption]. Provided options are:

• MainClass(mainClassName: String) Specifies the Main-Class attribute in the manifest. By default, this option is included with the value of the mainClass method if it is defined. When mainClass is not specified explicitly, the package task will try to determine which class to use automatically. If exactly one main class is detected, it is used. If multiple main classes are detected, a warning is printed and no Main-Class attribute is added to the manifest.
• ManifestAttributes(attributes: (java.util.jar.Attributes.Name, String)*) or ManifestAttributes(attributes: (String, String)*) Defines main attributes to add to the manifest.
• JarManifest(m: Manifest) Specifies the manifest to use for the jar. The default manifest includes the Main-Class attribute if mainClass (as described above) is not empty and the Class-Path attribute if manifestClassPath is not empty.

Document Options

Method documentOptions specifies the options for the API documentation tasks doc and docTests. Provided options are:

• LinkSource
• NoComment
• access(access: Access.Value)
• documentBottom(bottomText: String)
• documentCharset(charset: String)
• documentTitle(title: String)
• documentFooter(footerText: String)
• documentHeader(headerText: String)
• stylesheetFile(path: Path)
• documentTop(topText: String)
• windowTitle(title: String)

By default, a window and document title are specified in 2.7 and a document title is specified in 2.8 (window title does not exist at this time).

Test Options

Method testOptions specifies the options for the test action.

• ExcludeTests(tests: Iterable[String]) Specifies the class names of tests that should not be run.
• TestFilter(filter: String => Boolean) Specifies a function that returns true if the test should be run.
• TestListeners(listeners: Iterable[TestReportListener]) Specifies the reporters used when running tests. testOptions by default includes a reporter that sends output to the project logger.
• TestArgument(args: String*) Specifies arguments to pass to the test framework when running tests.
• TestArgument(tf: TestFramework, args: String*) Specifies arguments to pass to a specific test framework when running tests.

Changing Paths

The only paths in sbt that are completely fixed are the locations of the files in the project directory. The other paths, such as the path to sources, jars, and outputs, are configurable. Overriding the default paths is described in this section. See Paths for details on constructing paths.

Paths in sbt are incrementally built up out of path components so that you can easily rename any directory in the path or modify the path structure. You should always refer to a path by its sbt method instead of constructing a Path literal. For example, always refer to the output directory as outputPath instead of path("target") and refer to the directory that classes are compiled to as mainCompilePath instead of "target" / "classes".

The paths and the names used to construct them are defined in BasicProjectPaths, which is mixed into the default project definition, as members that you can override. If you only want to rename a directory, override the member that specifies the name. For example, to rename the output directory from target to build,

  override def outputDirectoryName = "build"

The outputs for compilation and API documentation are defined as:

  def outputPath = crossPath(outputDirectoryName)

  def mainCompilePath = outputPath / compileDirectoryName
  def docPath = outputPath / docDirectoryName
  def analysisPath = outputPath / analysisDirectoryName

and so the directory name will be used by subpaths as well.

Similarly, you could rearrange the source directory from

src/
  main/
    scala/
    resources/
  test/
    scala/
    resources/

to

src/
resources/
test-src/
test-resources/

by specifying the following in your project definition:

  override def mainScalaSourcePath = "src"
  override def mainResourcesPath = "resources"
	
  override def testScalaSourcePath = "test-src"
  override def testResourcesPath = "test-resources"

The paths directly used by the default actions are listed below. Other paths are only used to build up these paths. If redefined, care should be taken to keep these paths distinct from each other.

• dependencyPath- This is the location of manually managed jars.
• managedDependencyPath - This is the location that automatic dependency management puts downloaded artifacts. When executed, the clean-lib action removes this directory.
• mainScalaSourcePath - The path to Scala sources comprising the project.
• mainJavaSourcePath: The path to the main Java sources for the project.
• mainResourcesPath - The path to resources to include in the project jar.
• testScalaSourcePath - The path to Scala sources defining tests.
• testJavaSourcePath: The path to the test Java sources for the project.
• testResourcesPath - The path to resources to include in the test jar.
• outputPath - The path containing all sbt-generated files (besides the managed artifacts that go in managedDependencyPath). All files generated by tasks should go in this directory. When executed, the clean action removes this directory. The following are subpaths of outputPath:
• mainDocPath - The directory where API documentation for main sources is generated.
• testDocPath - The directory where API documentation for test sources is generated.
• mainCompilePath - The directory containing compiled main classes.
• testCompilePath - The directory containing compiled test classes.
• mainAnalysisPath - The directory used to store the analysis done at compile time. This includes files that record dependencies between source files.
• testAnalysisPath - The directory used to store the analysis done at test compile time. This includes files that record dependencies between source files and the class names of tests.

Additionally, web applications use these paths defined in sbt.WebProjectPaths:

• webappPath - The location of web application resources.
• temporaryWarPath - The intermediate location used to create a war file or to run Jetty. It should be a subpath of outputPath.

• webstartOutputDirectory - The directory that the webstart products are created in.
• webstartMainJar - The jar that contains the entry point to the application.
• webstartLibDirectory - The directory that libraries will go in.
• jnlpFile - The location in the webstart output directory to write the JNLP XML file to.
• webstartZip - Some containing the location to write the zipped output directory to or None if no zip of the output directory should be created
• jnlpPath - The directory containing resources to copy to the webstart output directory.
• jnlpResourcesPath - The resources to include in the webstart output directory. By default this is everything in jnlpPath