| Deletions are marked like this. | Additions are marked like this. |
| Line 5: | Line 5: |
| Custom Settings and Tasks |
ここでは、君自身が設定とタスクを作成できるようにする。 このガイドの以前のページ、特にbuild.sbtとmore about settingsについて読んだことが前提だ。 |
| Line 7: | Line 8: |
| Page History | |
| Line 9: | Line 9: |
| Previous Getting Started Guide page 13 of 14. Next | == キーを定義する == |
| Line 11: | Line 11: |
| This page gets you started creating your own settings and tasks. |
[[http://harrah.github.com/xsbt/latest/sxr/Keys.scala.html|Keys]] is packed with examples illustrating how to define keys. Most of the keys are implemented in [[http://harrah.github.com/xsbt/latest/sxr/Defaults.scala.html|デフォルト]]. |
| Line 13: | Line 14: |
|
To understand this page, be sure you've read earlier pages in the Getting Started Guide, especially build.sbt and more about settings. Defining a key |
キーは三つの中の一つのタイプを持つ。 SettingKeyとTaskKeyについては.sbt build definitionで説明した。 InputKeyについては「Input Tasks」ページを参照のこと。 |
| Line 16: | Line 18: |
|
Keys is packed with examples illustrating how to define keys. Most of the keys are implemented in Defaults. Keys have one of three types. SettingKey and TaskKey are described in .sbt build definition. Read about InputKey on the Input Tasks page. |
Keysの中から例を示す。 |
| Line 21: | Line 20: |
| {{{ | |
| Line 24: | Line 23: |
| }}} | |
| Line 25: | Line 25: |
| 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."). |
Keyのコンストラクタは二つの文字列パラメータを持つ、キーの名前("scala-version")とドキュメント文字列だ ("The version of scala used for building."). |
| Line 27: | Line 28: |
| Remember from .sbt build definition that the type parameter T in SettingKey[T] indicates the type of value a setting has. T in TaskKey[T] indicates the type of the task's result. Also remember from .sbt build definition that a setting has a fixed value until project reload, while a task is re-computed for every "task execution" (every time someone types a command at the sbt interactive prompt or in batch mode). |
「.sbt build definition」を思い起こそう、SettingKey[T]のタイプパラメータTはsettingが持つ値のタイプを示している。TaskKey[T]のTはタスクの「結果」タイプを示している。 「.sbt build definition」では、settingが固定的な値を持ち、プロジェクトreloadされるまでは変更されないが、これに対して、タスクはタスク実行のたびに再計算されることを説明した（つまり、sbt対話モードやバッチモードで誰かがコマンドを入力するたび）。 |
| Line 29: | Line 31: |
|
Keys may be defined in a .scala file (as described in .scala build definition), or in a plugin (as described in using plugins). Any val found in a Build object in your .scala build definition files, or any val found in a Plugin object from a plugin, will be imported automatically into your .sbt files. Implementing a task |
キーは.scalaファイル中で定義できる（「.scala build definition」で説明した）、あるいはプラグイン中でも定義できる（「using plugins」で説明したように）。 .scalaファイルのBuildオブジェクト中にあるvalも、プラグインのPluginオブジェクト中にあるvalも、自動的に.sbtファイルにインポートされる。 |
| Line 32: | Line 34: |
| Once you've defined a key, you'll need to use it in some task. You could be defining your own task, or you could be planning to redefine an existing task. Either way looks the same; if the task has no dependencies on other settings or tasks, use := to associate some code with the task key: | |
| Line 34: | Line 35: |
|
== タスクの実装 == キーを定義したなら、それを何らかのタスク中で使う必要がある。 君自身のタスク中で使っても良いし、既存のタスクを再定義してもよい。 いずれにしても同じだ。もしタスクが他のsettingやタスクへの依存を持たないなら、 タスクキーにコードを結びつけるのに「:=」を使う。 {{{ |
|
| Line 41: | Line 51: |
| }}} | |
| Line 42: | Line 53: |
| If the task has dependencies, you'd use <<= instead of course, as discussed in more about settings. | タスクが何らかの依存を持つなら、当然<<=を使う。「more about settings」で説明したようにね。 |
| Line 44: | Line 55: |
| The hardest part about implementing tasks is often not sbt-specific; tasks are just Scala code. The hard part could be writing the "meat" of your task that does whatever you're trying to do. For example, maybe you're trying to format HTML in which case you might want to use an HTML library (you would add a library dependency to your build definition and write code based on the HTML library, perhaps). |
タスクの実装で最も難しい部分は、sbt特有の事柄では無いことが多い。 タスクは単なるScalaプログラムなのだ。 難しい部分は、君が何をしようとしているかという、その「肉」の部分を記述することだ。 例えば、HTMLをフォーマットしたいとするなら、HTMLのライブラリが必要になるよね。 （たぶん、ビルド定義にライブラリ依存を記述して、そのHTMLライブラリに基づくコードを書くよね）。 |
| Line 46: | Line 61: |
|
sbt has some utility libraries and convenience functions, in particular you can often use the convenient APIs in IO to manipulate files and directories. Extending but not replacing a task |
sbtは、君がファイルやディレクトリのIO操作によく使うAPIと同様の、便利な関数をユーティリティライブラリとして持っている。 |
| Line 49: | Line 63: |
| If you want to run an existing task while also taking another action, use ~= or <<= to take the existing task as input (which will imply running that task), and then do whatever else you like after the previous implementation completes. | == タスクを拡張するが、置換はしない == |
| Line 51: | Line 65: |
| // These two settings are equivalent |
もし既存のタスクをそのまま実行させて、何らかのアクションを付け加えたいのであれば、 既存のタスクを入力として~=や<<=を使うのがいい（そのタスクの実行を含意している）。 以前の実装の実行が終了した後で、君がしたいことをする。 {{{ // 次の二つは等価だ |
| Line 54: | Line 73: |
| }}} | |
| Line 55: | Line 75: |
| Use plugins! | == プラグインを使う！ == |
| Line 57: | Line 77: |
| If you find you have a lot of custom code in .scala files, consider moving it to a plugin for re-use across multiple projects. |
もし、.scalaファイル中にたくさんのカスタムコードが必要になるようなら、 それを複数のプロジェクトで利用できるようにプラグイン化することを考えよう。 |
| Line 59: | Line 80: |
|
It's very easy to create a plugin, as teased earlier and discussed at more length here. Next |
プラグインを書くのは非常に簡単だ、以前に説明したように。 |
| Line 62: | Line 82: |
| This page has been a quick taste; there's much much more about custom tasks on the Tasks page. |
このページは非常に簡単に説明している。カスタムタスクについては[[sbt/dt_Tasks|タスク]]を参照してほしい |
カスタム設定とタスク
https://github.com/harrah/xsbt/wiki/Getting-Started-Custom-Settingsの訳(2011/10/30時点)
ここでは、君自身が設定とタスクを作成できるようにする。 このガイドの以前のページ、特にbuild.sbtとmore about settingsについて読んだことが前提だ。
キーを定義する
is packed with examples illustrating how to define keys. Most of the keys are implemented in デフォルト.
キーは三つの中の一つのタイプを持つ。 SettingKeyとTaskKeyについては.sbt build definitionで説明した。 InputKeyについては「Input Tasks」ページを参照のこと。
Keysの中から例を示す。 Some examples from Keys:
val scalaVersion = SettingKey[String]("scala-version", "The version of Scala used for building.")
val clean = TaskKey[Unit]("clean", "Deletes files produced by the build, such as generated sources, compiled classes, and task caches.")Keyのコンストラクタは二つの文字列パラメータを持つ、キーの名前("scala-version")とドキュメント文字列だ ("The version of scala used for building.").
「.sbt build definition」を思い起こそう、SettingKey[T]のタイプパラメータTはsettingが持つ値のタイプを示している。TaskKey[T]のTはタスクの「結果」タイプを示している。 「.sbt build definition」では、settingが固定的な値を持ち、プロジェクトreloadされるまでは変更されないが、これに対して、タスクはタスク実行のたびに再計算されることを説明した（つまり、sbt対話モードやバッチモードで誰かがコマンドを入力するたび）。
キーは.scalaファイル中で定義できる（「.scala build definition」で説明した）、あるいはプラグイン中でも定義できる（「using plugins」で説明したように）。 .scalaファイルのBuildオブジェクト中にあるvalも、プラグインのPluginオブジェクト中にあるvalも、自動的に.sbtファイルにインポートされる。
タスクの実装
キーを定義したなら、それを何らかのタスク中で使う必要がある。 君自身のタスク中で使っても良いし、既存のタスクを再定義してもよい。 いずれにしても同じだ。もしタスクが他のsettingやタスクへの依存を持たないなら、 タスクキーにコードを結びつけるのに「:=」を使う。
sampleStringTask := System.getProperty("user.home")
sampleIntTask := {
val sum = 1 + 2
println("sum: " + sum)
sum
}タスクが何らかの依存を持つなら、当然<<=を使う。「more about settings」で説明したようにね。
タスクの実装で最も難しい部分は、sbt特有の事柄では無いことが多い。 タスクは単なるScalaプログラムなのだ。 難しい部分は、君が何をしようとしているかという、その「肉」の部分を記述することだ。 例えば、HTMLをフォーマットしたいとするなら、HTMLのライブラリが必要になるよね。 （たぶん、ビルド定義にライブラリ依存を記述して、そのHTMLライブラリに基づくコードを書くよね）。
sbtは、君がファイルやディレクトリのIO操作によく使うAPIと同様の、便利な関数をユーティリティライブラリとして持っている。
タスクを拡張するが、置換はしない
もし既存のタスクをそのまま実行させて、何らかのアクションを付け加えたいのであれば、 既存のタスクを入力として~=や<<=を使うのがいい（そのタスクの実行を含意している）。 以前の実装の実行が終了した後で、君がしたいことをする。
// 次の二つは等価だ
intTask <<= intTask map { (value: Int) => value + 1 }
intTask ~= { (value: Int) => value + 1 }
プラグインを使う！
もし、.scalaファイル中にたくさんのカスタムコードが必要になるようなら、 それを複数のプロジェクトで利用できるようにプラグイン化することを考えよう。
プラグインを書くのは非常に簡単だ、以前に説明したように。
このページは非常に簡単に説明している。カスタムタスクについてはタスクを参照してほしい
次はサマリ