Need explanation about SBT's key variables in build.sbt

Question

I am trying to enable forking in sbt for test task only, which excluding the rests of test command (test-only, test:compile, etc).

At first I thought the solution would be:

fork in test := true

But then I saw on the documentation, doing that will enable forking all test tasks which is not what I want.

I also found out there is Test variable (has uppercase first letter). What is the difference between test and Test?

Then I also saw another example:

fork in (Test, run) := true

which sbt manual said it's for forking test:run and test:runMain:. At first I thought (Test, run) means test:run, but seeing another example below, it seems the meaning is not like that:

// sets the working directory for `run` and `runMain` only
baseDirectory in (Compile,run) := file("/path/to/working/directory/")

So there are variables with capital first letter (e.g. Test, Compile, Runtime), and variables with lowercase first letter (e.g. test, testOnly, compile, console, run), the latter seems corresponds to sbt commands, but I'm not clear about the former. So what's the difference between them?

Answer 1

Generic background

sbt has three scope axis (think of it as a 3D space) for all its variables (keys). Alternatively, you can think of it as 3-tired namespaces.

1) Project, 2) Configuration, and 3) Task

From sbt interactive:

<project-id>/config:intask::key

So you can say execute from project X (D-1) and configuration Compile (D-2) the run task (D-3). This will execute the main function found in the compile (under main/src folder) code of project X.

sbt> projectX/compile:run

Similarly you can say execute run in the Test configuration of project X. This will now execute the main method (say you have one defined) that is under the test/src folder.

sbt> projectX/test:run

Now, tasks also have keys (internal configuration variables). For example:

sbt> show projectX/compile:compile::sources

This will show the source files used by the compile task of Project-X's Compile configuration (when you compile just your code, not the tests).

sbt> show projectX/test:compile::sources

This will show the source files used by the compile task of Project-X's Test configuration (when you compile just your test files).

Naming in SBT DSL

sbt has different convention for naming tasks and scopes while you are writing in its DSL (inside .sbt files) and while executing tasks interactively via the sbt cli.

projectX/test:compile::sources

translates to

sources in (Test,compile) in projectX

So to get to your question. Test with capital T is the configuration scope. Similar Compile with capital C is the configuration scope. The lowercase compile, test etc are your tasks.

Now, sbt has a lot of default scopes. For example, if you just enter sbt and type compile, it will actually execute the compile task under the Compile configuration of the Root project.