Configurations

Introduction

Ivy configurations are a useful feature for your build when you use managed dependencies. They are essentially named sets of dependencies. You can read the full Ivy documentation for details. Their use in sbt is described on this page.

Usage

The built-in use of configurations in sbt is similar to scopes in Maven. sbt adds dependencies to different classpaths by the configuration that they are defined in. See the description of Maven Scopes for details.

You put a dependency in a configuration by selecting one or more of its configurations to map to one or more of your project's configurations. The most common case is to have one of your configurations A use a dependency's configuration B. The mapping for this looks like "A->B". To apply this mapping to a dependency, add it to the end of your dependency definition:

  val st = "org.scala-tools.testing" % "scalatest" % "0.9.5" % "test->default"

This says that your project's test configuration uses ScalaTest's default configuration. Again, see the Ivy documentation for more advanced mappings. Most projects published to Maven repositories will use the default or compile configuration. sbt itself, however, publishes different jars to different configurations for each version of Scala that it supports. The jar compiled against Scala 2.7.5 is published to the "2.7.5" configuration. This is probably atypical, however, and the better solution for this particular case is to use cross-building.

A more useful application of configurations is to group dependencies that are not used on classpaths. For example, your might use a "js" configuration to automatically download jQuery and then include it in your jar by overriding mainResources. This is what Scala X-Ray does, for example:

  def jquery_version = "1.3.2"
  val js = config("js") hide
  val jquery = "jquery" % "jquery" % jquery_version % "js->default" from ("http://jqueryjs.googlecode.com/files/jquery-" + jquery_version + ".min.js")
  override def mainResources = super.mainResources +++ descendents(configurationPath(js) ##, "*.js")

The config method defines a new configuration with name "js" and makes it private to the project so that it is not used for publishing.

As of sbt 0.5.5, a configuration without a mapping (no "->") is mapped to default or compile. The -> is only needed when mapping to a different configuration than those. The ScalaTest dependency above can then be shortened to:

  val st = "org.scala-tools.testing" % "scalatest" % "0.9.5" % "test"