Use cases for different sbt Key operators

Question

The documentation for sbt seems to be really lacking here, so I'd like to get a definitive answer on this: what is the difference between "+=", "++=", "<+=", "<++=", and "<<=" when operating on Keys?

Answer 1

You cannot find documentation, because as @JacekLaskowski correctly pointed out all operators except for +=, ++= and := are deprecated.

You can however find the Documentation if you switch to older version of sbt.

If you however are stuck to older version, this is their meaning (via documentation):

• += and ++= append to previous value, where first appends single element and next appends a Seq
• ~= transforms value, e.g. you want to use value stored in a setting to get a new setting.
• <<= depends on another key, for example if you call organization <<= name, then organization value is equal to name value. You can depend on multiple values, e.g. organization <<= (name, version) { (n, v) => /* do something with values */ }
• <+= and <++= are appending with dependencies, like the append, but you can use another's setting value to compute new value

Said that, @JacekLaskowski is right, and if you are using sbt 13.x or greater you should not have to use those operators in favours of macros.

Answer 2

Quoting Task v. Setting keys:

A TaskKey[T] is said to define a task.

sbt's map describing the project can keep around a fixed string value for a setting such as name, but it has to keep around some executable code for a task such as compile -- even if that executable code eventually returns a string, it has to be re-run every time.

A given key always refers to either a task or a plain setting. That is, "taskiness" (whether to re-run each time) is a property of the key, not the value.

In other words, settings are immutable and initialized at build startup (similar to vals in Scala) while tasks are executed every time they're called (similar to defs in Scala).

Quoting Defining tasks and settings:

Using :=, you can assign a value to a setting and a computation to a task. For a setting, the value will be computed once at project load time. For a task, the computation will be re-run each time the task is executed.

Quoting Appending to previous values: += and ++=:

Assignment with := is the simplest transformation, but keys have other methods as well. If the T in SettingKey[T] is a sequence, i.e. the key's value type is a sequence, you can append to the sequence rather than replacing it.

+= will append a single element to the sequence. ++= will concatenate another sequence.

Wrapping it up, you should only be concerned with := (assignment macro), += (append macro) and ++= (concatenation macro). The remaining ones, i.e. <<=, <+= and <++=, are no longer recommended for common use cases.

As a matter of fact, all operations can be expressed with the simple assignment macro := (paraphrasing the upcoming book SBT in Action).

Are you really sure, the docs are "really lacking here"?! I doubt.

Answer 3

When the operators were deprecated, is there any documentation or porting guide what they mean or how to translate them to a currently used syntax?

You can see example of such translation in recent (Dec. 2016) commits (in scala/scala itself) like:

• fd3610c: avoid deprecated sbt 0.12 operators,
• c6e79dd: Avoid 2 more deprecated sbt 0.12 operators

You will see:

-  incOptions <<= (incOptions in LocalProject("root")),
+  incOptions := (incOptions in LocalProject("root")).value,

or

-    packagedArtifact in (Compile, packageBin) <<= (artifact in (Compile, packageBin), bundle).identityMap,
+    packagedArtifact in (Compile, packageBin) := (((artifact in (Compile, packageBin)).value, bundle.value)),

You can see more about the deprecation of those operators in sbt PR 2711, sbt PR 2716 and sbt/notes/0.13.13/ops_deprecation.md.