From 0ff96da70e70cd48672a96800c4ae4ef37cc6857 Mon Sep 17 00:00:00 2001 From: Mark Harrah Date: Wed, 18 Sep 2013 10:27:19 -0400 Subject: [PATCH] Docs: clean up Getting-Started/Basic-Def, including an example of defining a key. Fixes #862. --- src/sphinx/Getting-Started/Basic-Def.rst | 83 +++++++++++++++--------- 1 file changed, 52 insertions(+), 31 deletions(-) diff --git a/src/sphinx/Getting-Started/Basic-Def.rst b/src/sphinx/Getting-Started/Basic-Def.rst index 734bb6ae2..ea302d11a 100644 --- a/src/sphinx/Getting-Started/Basic-Def.rst +++ b/src/sphinx/Getting-Started/Basic-Def.rst @@ -132,44 +132,52 @@ the next begins. program. These expressions have to be split up and passed to the compiler individually. -If you want a single Scala program, use :doc:`.scala files ` -rather than `.sbt` files; `.sbt` files are optional. -:doc:`Later on ` this guide explains how to use -`.scala` files. (Preview: the same settings expressions found in a -`.sbt` file can always be listed in a `Seq[Setting]` in a `.scala` -file instead.) +Keys +---- -Keys are defined in the Keys object ------------------------------------ +Types +~~~~~ + +There are three flavors of key: + +- `SettingKey[T]`: a key for a value computed once (the value is + computed one time when loading the project, and kept around). +- `TaskKey[T]`: a key for a value, called a *task*, + that has to be recomputed each time, potentially creating side effects. +- `InputKey[T]`: a key for a task that has command line arguments as + input. The Getting Started Guide doesn't cover `InputKey`, but when + you finish this guide, check out :doc:`/Extending/Input-Tasks` for more. + + +Built-in Keys +~~~~~~~~~~~~~ The built-in keys are just fields in an object called `Keys <../../sxr/Keys.scala.html>`_. A `build.sbt` implicitly has an `import sbt.Keys._`, so `sbt.Keys.name` can be referred to as `name`. -Custom keys may be defined in a :doc:`.scala file ` or a :doc:`plugin `. +Custom Keys +~~~~~~~~~~~ -Other ways to transform settings --------------------------------- +Custom keys may be defined with their respective creation methods: `settingKey`, `taskKey`, and `inputKey`. +Each method expects the type of the value associated with the key as well as a description. +The name of the key is taken from the `val` the key is assigned to. +For example, to define a key for a new task called `hello`, :: -Replacement with `:=` is the simplest transformation, but there are -several others. For example you can append to a list value with `+=`. + lazy val hello = taskKey[Unit]("An example task") -The other transformations require an understanding of :doc:`scopes `, so the :doc:`next page ` is about -scopes and the :doc:`page after that ` goes into more detail about settings. +Here we have used the fact that an `.sbt` file can contain `val`\ s and `def`\ s in addition to settings. +All such definitions are evaluated before settings regardless of where they are defined in the file. +`val`\ s and `def`\ s must be separated from settings by blank lines. -Task Keys ---------- +.. note:: -There are three flavors of key: + Typically, `lazy val`\ s are used instead of `val`\ s to avoid initialization order problems. -- `SettingKey[T]`: a key with a value computed once (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. -- `InputKey[T]`: a task key which has command line arguments as - input. The Getting Started Guide doesn't cover `InputKey`, but when - you finish this guide, check out :doc:`/Extending/Input-Tasks` for more. + +Task v. Setting keys +~~~~~~~~~~~~~~~~~~~~ A `TaskKey[T]` is said to define a *task*. Tasks are operations such as `compile` or `package`. They may return `Unit` (`Unit` is @@ -191,13 +199,25 @@ time. is, "taskiness" (whether to re-run each time) is a property of the key, not the value. -Using `:=`, you can assign a computation to a task, and that -computation will be re-run each time: -:: +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. + +For example, to implement the `hello` task from the previous section, :: hello := { println("Hello!") } +We already saw an example of defining settings when we defined the project's name, :: + + name := "hello" + +Types for tasks and settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + From a type-system perspective, the `Setting` created from a task key is slightly different from the one created from a setting key. `taskKey := 42` results in a `Setting[Task[T]]` while @@ -206,9 +226,9 @@ makes no difference; the task key still creates a value of type `T` when the task executes. The `T` vs. `Task[T]` type difference has this implication: a -setting key can't depend on a task key, because a setting key is -evaluated only once on project load, and not re-run. More on this in -:doc:`more about settings `, coming up +setting can't depend on a task, because a setting is +evaluated only once on project load and is not re-run. +More on this in :doc:`more about settings `, coming up soon. Keys in sbt interactive mode @@ -248,6 +268,7 @@ There are some implied default imports, as follows: the contents of any `Build` or `Plugin` objects in those files will be imported. More on that when we get to :doc:`.scala build definitions `.) + Adding library dependencies ---------------------------