========================================= Interacting with the Configuration System ========================================= Central to sbt is the new configuration system, which is designed to enable extensive customization. The goal of this page is to explain the general model behind the configuration system and how to work with it. The Getting Started Guide (see :doc:`.sbt files `) describes how to define settings; this page describes interacting with them and exploring them at the command line. Selecting commands, tasks, and settings ======================================= A fully-qualified reference to a setting or task looks like: .. code-block:: console {}/config:inkey::key This "scoped key" reference is used by commands like `last` and `inspect` and when selecting a task to run. Only `key` is usually required by the parser; the remaining optional pieces select the scope. These optional pieces are individually referred to as scope axes. In the above description, `{}` and `/` specify the project axis, `config:` is the configuration axis, and `inkey` is the task-specific axis. Unspecified components are taken to be the current project (project axis) or auto-detected (configuration and task axes). An asterisk (`*`) is used to explicitly refer to the `Global` context, as in `*/*:key`. Selecting the configuration --------------------------- In the case of an unspecified configuration (that is, when the `config:` part is omitted), if the key is defined in `Global`, that is selected. Otherwise, the first configuration defining the key is selected, where order is determined by the project definition's `configurations` member. By default, this ordering is `compile, test, ...` For example, the following are equivalent when run in a project `root` in the build in `/home/user/sample/`: .. code-block:: console > compile > compile:compile > root/compile > root/compile:compile > {file:/home/user/sample/}root/compile:compile As another example, :key:`run` by itself refers to `compile:run` because there is no global :key:`run` task and the first configuration searched, :key:`compile`, defines a :key:`run`. Therefore, to reference the :key:`run` task for the `Test` configuration, the configuration axis must be specified like `test:run`. Some other examples that require the explicit `test:` axis: .. code-block:: console > test:consoleQuick > test:console > test:doc > test:package Task-specific Settings ---------------------- Some settings are defined per-task. This is used when there are several related tasks, such as :key:`package`, :key:`packageSrc`, and :key:`packageDoc`, in the same configuration (such as :key:`compile` or :key:`test`). For package tasks, their settings are the files to package, the options to use, and the output file to produce. Each package task should be able to have different values for these settings. This is done with the task axis, which selects the task to apply a setting to. For example, the following prints the output jar for the different package tasks. .. code-block:: console > package::artifactPath [info] /home/user/sample/target/scala-2.8.1.final/demo_2.8.1-0.1.jar > packageSrc::artifactPath [info] /home/user/sample/target/scala-2.8.1.final/demo_2.8.1-0.1-src.jar > packageDoc::artifactPath [info] /home/user/sample/target/scala-2.8.1.final/demo_2.8.1-0.1-doc.jar > test:package::artifactPath [info] /home/user/sample/target/scala-2.8.1.final/root_2.8.1-0.1-test.jar Note that a single colon `:` follows a configuration axis and a double colon `::` follows a task axis. Discovering Settings and Tasks ============================== This section discusses the `inspect` command, which is useful for exploring relationships between settings. It can be used to determine which setting should be modified in order to affect another setting, for example. Value and Provided By --------------------- The first piece of information provided by `inspect` is the type of a task or the value and type of a setting. The following section of output is labeled "Provided by". This shows the actual scope where the setting is defined. For example, .. code-block:: console > inspect libraryDependencies [info] Setting: scala.collection.Seq[sbt.ModuleID] = List(org.scalaz:scalaz-core:6.0-SNAPSHOT, org.scala-tools.testing:scalacheck:1.8:test) [info] Provided by: [info] {file:/home/user/sample/}root/*:libraryDependencies ... This shows that :key:`libraryDependencies` has been defined on the current project (`{file:/home/user/sample/}root`) in the global configuration (`*:`). For a task like :key:`update`, the output looks like: .. code-block:: console > inspect update [info] Task: sbt.UpdateReport [info] Provided by: [info] {file:/home/user/sample/}root/*:update ... Related Settings ---------------- The "Related" section of `inspect` output lists all of the definitions of a key. For example, .. code-block:: console > inspect compile ... [info] Related: [info] test:compile This shows that in addition to the requested `compile:compile` task, there is also a `test:compile` task. Dependencies ------------ Forward dependencies show the other settings (or tasks) used to define a setting (or task). Reverse dependencies go the other direction, showing what uses a given setting. `inspect` provides this information based on either the requested dependencies or the actual dependencies. Requested dependencies are those that a setting directly specifies. Actual settings are what those dependencies get resolved to. This distinction is explained in more detail in the following sections. Requested Dependencies ~~~~~~~~~~~~~~~~~~~~~~ As an example, we'll look at :key:`console`: .. code-block:: console > inspect console ... [info] Dependencies: [info] compile:console::fullClasspath [info] compile:console::scalacOptions [info] compile:console::initialCommands [info] compile:console::cleanupCommands [info] compile:console::compilers [info] compile:console::taskTemporary-directory [info] compile:console::scalaInstance [info] compile:console::streams ... This shows the inputs to the :key:`console` task. We can see that it gets its classpath and options from :key:`fullClasspath` and `scalacOptions(for console)`. The information provided by the `inspect` command can thus assist in finding the right setting to change. The convention for keys, like :key:`console` and :key:`fullClasspath`, is that the Scala identifier is camel case, while the String representation is lowercase and separated by dashes. The Scala identifier for a configuration is uppercase to distinguish it from tasks like :key:`compile` and :key:`test`. For example, we can infer from the previous example how to add code to be run when the Scala interpreter starts up: .. code-block:: console > set initialCommands in Compile in console := "import mypackage._" > console ... import mypackage._ ... `inspect` showed that :key:`console` used the setting `compile:console::initialCommands`. Translating the :key:`initialCommands` string to the Scala identifier gives us :key:`initialCommands`. :key:`compile` indicates that this is for the main sources. `console::` indicates that the setting is specific to :key:`console`. Because of this, we can set the initial commands on the :key:`console` task without affecting the :key:`consoleQuick` task, for example. Actual Dependencies ~~~~~~~~~~~~~~~~~~~ `inspect actual ` shows the actual dependency used. This is useful because delegation means that the dependency can come from a scope other than the requested one. Using `inspect actual`, we see exactly which scope is providing a value for a setting. Combining `inspect actual` with plain `inspect`, we can see the range of scopes that will affect a setting. Returning to the example in Requested Dependencies, .. code-block:: console > inspect actual console ... [info] Dependencies: [info] compile:scalacOptions [info] compile:fullClasspath [info] *:scalaInstance [info] */*:initialCommands [info] */*:cleanupCommands [info] */*:taskTemporaryDirectory [info] *:console::compilers [info] compile:console::streams ... For `initialCommands`, we see that it comes from the global scope (`*/*:`). Combining this with the relevant output from `inspect console`: .. code-block:: console compile:console::initialCommands we know that we can set :key:`initialCommands` as generally as the global scope, as specific as the current project's :key:`console` task scope, or anything in between. This means that we can, for example, set :key:`initialCommands` for the whole project and will affect :key:`console`: .. code-block:: console > set initialCommands := "import mypackage._" ... The reason we might want to set it here this is that other console tasks will use this value now. We can see which ones use our new setting by looking at the reverse dependencies output of `inspect actual`: .. code-block:: console > inspect actual initialCommands ... [info] Reverse dependencies: [info] test:console [info] compile:consoleQuick [info] compile:console [info] test:consoleQuick [info] *:consoleProject ... We now know that by setting :key:`initialCommands` on the whole project, we affect all console tasks in all configurations in that project. If we didn't want the initial commands to apply for :key:`consoleProject`, which doesn't have our project's classpath available, we could use the more specific task axis: .. code-block:: console > set initialCommands in console := "import mypackage._" > set initialCommands in consoleQuick := "import mypackage._"` or configuration axis: .. code-block:: console > set initialCommands in Compile := "import mypackage._" > set initialCommands in Test := "import mypackage._" The next part describes the Delegates section, which shows the chain of delegation for scopes. Delegates --------- A setting has a key and a scope. A request for a key in a scope A may be delegated to another scope if A doesn't define a value for the key. The delegation chain is well-defined and is displayed in the Delegates section of the `inspect` command. The Delegates section shows the order in which scopes are searched when a value is not defined for the requested key. As an example, consider the initial commands for :key:`console` again: .. code-block:: console > inspect console::initialCommands ... [info] Delegates: [info] *:console::initialCommands [info] *:initialCommands [info] {.}/*:console::initialCommands [info] {.}/*:initialCommands [info] */*:console::initialCommands [info] */*:initialCommands ... This means that if there is no value specifically for `*:console::initialCommands`, the scopes listed under Delegates will be searched in order until a defined value is found.