This document outlines the desired use cases of BuildLevel feature.
User Story: Changing the build level of test.sbt
User splits up her *.sbt into compile.sbt, test.sbt, and publish.sbt. Here's test.sbt:
buildLevel in ThisScript := test
libraryDependency += "org.specs2" %% "specs2" % "2.3.10" % "test"
When she launches sbt, test.sbt is read normally.
When she launches sbt with sbt.buildLevel=-test, any settings written in tesst.sbt are ignored.
User Story: Setting the build level of plugins
User splits up her project/plugins.sbt into compile.sbt, test.sbt and publish.sbt. Here's project/publish.sbt:
buildLevel in ThisScript := publish
addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "0.20.0")
Suppose sbt-assembly 0.20.0 is an auto plugin that loads settings into all Scala projects automatically.
When she launches sbt, sbt-assembly is loaded normally.
When she launches sbt with sbt.buildLevel=-publish, the plugin is no longer loaded.
User Story: Optional global settings
User splits up her ~/.sbt/0.13/plugins/plugins.sbt into idea.sbt etc. Here's ~/.sbt/0.13/plugins/idea.sbt:
buildLevel in ThisScript := BuildLevel(name = "idea", optional = true)
addSbtPlugin("com.github.mpeltonen" % "sbt-idea" % "1.6.0")
When she launches sbt, sbt-idea is not loaded automatically.
When she launches sbt with sbt.buildLevel=+idea, the plugin is loaded.
User Story: Scaling the build down to minimal
User splits up her *.sbt into compile.sbt, test.sbt, and publish.sbt, project/plugins.sbt into compile.sbt, test.sbt and publish.sbt each set to an appropriate buildLevel.
When she launches sbt with sbt.buildLevel=compile (notice no + sign in front of compile), only the setting sets scoped in compile are loaded. compile includes all built-in settings.
When she launches sbt with sbt.buildLevel=compile,publish, only the setting sets scoped in compile and publish are loaded.