Remove references to Key[T]

This type will disappear in future sbt versions.
Havoc Pennington 2011-10-18 14:51:23 -04:00
parent 1ad23997a5
commit a4af32ca0a
4 changed files with 22 additions and 19 deletions

@ -81,8 +81,10 @@ The expressions in `build.sbt` are independent of one another, and they are
expressions, rather than complete lines of Scala code. An implication of
this is that you can't define a `val` or `object` in `build.sbt`.
On the left, `name`, `version`, and `scalaVersion` are _keys_. A key is an
instance of `Key[T]` where `T` is the expected value type.
On the left, `name`, `version`, and `scalaVersion` are _keys_. A
key is an instance of `SettingKey[T]`, `TaskKey[T]`, or
`InputKey[T]` where `T` is the expected value type. The kinds
of key are explained more below.
Keys have a method called `:=`, which returns a `Setting[T]`. You could
use a Java-like syntax to call the method:
@ -95,7 +97,7 @@ But Scala allows `name := "hello"` instead (in Scala, any method can use either
The `:=` method on key `name` returns a `Setting`, specifically a
`Setting[String]`. `String` also appears in the type of `name` itself, which
is `Key[String]`. In this case, the returned `Setting[String]` is
is `SettingKey[String]`. In this case, the returned `Setting[String]` is
a transformation to add or replace the `name` key in sbt's map, giving it
the value `"hello"`.
@ -124,15 +126,15 @@ The other transformations require an understanding of [[scopes|Getting Started S
## Task Keys
While all keys extend the `Key[T]` trait, there are two important
subclasses of `Key`.
There are three flavors of key:
- `SettingKey[T]`: a key with a value that never changes (the value is
computed one time when loading the project, and kept around).
- `TaskKey[T]`: a key with a value that has to be recomputed each time,
potentially creating side effects.
- (We're ignoring a third subclass, `InputKey[T]`, for now. Check out
[[Input Tasks]] for more about it.)
- `InputKey[T]` which isn't covered in the Getting Started Guide
because it's not as commonly used. Check out [[Input Tasks]]
for more about it.
A `TaskKey[T]` is said to define a _task_. Tasks are operations such as
`compile` or `package`. They may return `Unit` (`Unit` is Scala for `void`),

@ -31,7 +31,7 @@ val scalaVersion = SettingKey[String]("scala-version", "The version of Scala use
val clean = TaskKey[Unit]("clean", "Deletes files produced by the build, such as generated sources, compiled classes, and task caches.")
```
The `Key` constructors have two string parameters: the name of the key
The key constructors have two string parameters: the name of the key
(`"scala-version"`) and a documentation string (`"The version of scala used for
building."`).

@ -33,7 +33,7 @@ lines in a `build.sbt` automatically end up in the list, but in a
## Appending to previous values: `+=` and `++=`
Replacement with `:=` is the simplest transformation, but keys have other
methods as well. If the `T` in `Key[T]` is a sequence, i.e. the key's value
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.
@ -100,9 +100,10 @@ Or a simpler example:
name ~= { _.toUpperCase }
```
The function you pass to the `~=` method will always have type `T => T`, if
the key has type `Key[T]`. The function transforms the key's value into another
value of the same type.
The function you pass to the `~=` method will always have type `T
=> T`, if the key has type `SettingKey[T]` or `TaskKey[T]`. The
function transforms the key's value into another value of the same
type.
## Computing a value based on other keys' values: `<<=`
@ -130,9 +131,9 @@ is just a key:
name <<= name
```
When treated as an `Initialize[T]`, a `Key[T]` computes its current value. So
`name <<= name` sets the value of `name` to the value that `name` already
had.
When treated as an `Initialize[T]`, a `SettingKey[T]` computes its
current value. So `name <<= name` sets the value of `name` to the
value that `name` already had.
It gets a little more useful if you set a key to a _different_ key. The keys
must have identical value types, though.
@ -200,7 +201,7 @@ tuple like `(1, "a")` (that one has type `(Int, String)`).
So say you have a tuple of three `Initialize` objects; its type would be
`(Initialize[A], Initialize[B], Initialize[C])`. The `Initialize` objects
could be keys, since all `Key[T]` are also instances of `Initialize[T]`.
could be keys, since all `SettingKey[T]` are also instances of `Initialize[T]`.
Here's a simple example, in this case all three keys are strings:
@ -227,7 +228,7 @@ So each key is already an `Initialize`; but you can combine any number of
simple `Initialize` (such as keys) into one composite `Initialize` by
placing them in tuples, and invoking the `apply` method.
The `<<=` method on `Key[T]` is expecting an `Initialize[T]`, so you can use
The `<<=` method on `SettingKey[T]` is expecting an `Initialize[T]`, so you can use
this technique to create an `Initialize[T]` with multiple dependencies on
arbitrary keys.
@ -251,7 +252,7 @@ You can use a more concise syntax in `build.sbt`, like this:
name <<= (name, organization, version) { (n, o, v) => "project " + n + " from " + o + " version " + v }
```
Here the tuple of `Initialize` (also a tuple of `Key`) works as a function,
Here the tuple of `Initialize` (also a tuple of `SettingKey`) works as a function,
taking the anonymous function delimited by `{}` as its argument, and returning an
`Initialize[T]` where `T` is the result type of the anonymous function.

@ -21,7 +21,7 @@ to know.
- [[Basic build definition|Getting Started Basic Def]]
- your build definition is one big list of `Setting` objects, where a
`Setting` transforms the set of key-value pairs sbt uses to perform tasks.
- to create a `Setting`, call one of a few methods on a `Key` (the `:=` and
- to create a `Setting`, call one of a few methods on a key (the `:=` and
`<<=` methods are particularly important).
- there is no mutable state, only transformation; for example, a `Setting`
transforms sbt's collection of key-value pairs into a new collection. It