diff --git a/Getting-Started/Getting-Started-Basic-Def.md b/Getting-Started/Getting-Started-Basic-Def.md index b4466cb..4a98395 100644 --- a/Getting-Started/Getting-Started-Basic-Def.md +++ b/Getting-Started/Getting-Started-Basic-Def.md @@ -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`), diff --git a/Getting-Started/Getting-Started-Custom-Settings.md b/Getting-Started/Getting-Started-Custom-Settings.md index 53f1d3c..35fbbcb 100644 --- a/Getting-Started/Getting-Started-Custom-Settings.md +++ b/Getting-Started/Getting-Started-Custom-Settings.md @@ -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."`). diff --git a/Getting-Started/Getting-Started-More-About-Settings.md b/Getting-Started/Getting-Started-More-About-Settings.md index bb07e30..858732a 100644 --- a/Getting-Started/Getting-Started-More-About-Settings.md +++ b/Getting-Started/Getting-Started-More-About-Settings.md @@ -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. diff --git a/Getting-Started/Getting-Started-Summary.md b/Getting-Started/Getting-Started-Summary.md index 4906772..8947d13 100644 --- a/Getting-Started/Getting-Started-Summary.md +++ b/Getting-Started/Getting-Started-Summary.md @@ -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