スコープ
https://github.com/harrah/xsbt/wiki/Getting-Started-Scopesの訳（2011/10/27時点)
ここではスコープを説明する。前のページ「.sbtビルド定義」を読んで理解していることを前提にするよ。
キーについてのすべて
nameのようなキーはsbtのキー・値マップの一つのエントリになるといった説明を以前にしたが、これは話を単純化したものだ。 実を言えば、それぞれのキーは複数のコンテキスト、これをスコープというのだが、に関連した値を持つことができるんだ。
例を示そう。
- ビルド定義の中に複数のプロジェクトがあるなら、キーはそれぞれのプロジェクトについて別の値を持ちうる。
- compileキーはメインソースについてと、テスト用ソースについては別の値を持ちうる。もし違ったやり方でコンパイルしたいのであれば。
- package-optionsキー（jarパッケージ生成時のオプションを含んでいる）はクラスファイルのパッケージング(package-bin)時とソースコードのパッケージング(package-src)時では異なる値を持つ。
キー名称に対する唯一の値は無く、スコープによって異なるんだ。
しかし、スコープ付のキーには唯一の値がある。
以前に説明したように、sbtがプロジェクトを表現するキー・値マップを作成するためにsettingのリストを処理するのだとしたら、そのキー・値マップの中のキーはスコープ付のキーだ。 ビルド定義（例えばbuild.sbt）中のそれぞれのsettingもまたスコープ付キーに適用される。
スコープはデフォルトのあることが多いのだが、しかしそれが間違っているなら、build.sbt中で望むスコープを指定しなければならない。
スコープ軸
スコープ軸とはタイプであり、そのタイプの各インスタンスはそれ自身のスコープを定義する。（つまり、各インスタンスはキーに対するそれ自身のユニークな値を持つ）。
スコープ軸としては三つある。
- プロジェクト
- コンフィギュレーション
- タスク
プロジェクト軸によるスコープ
もし一つのビルド中に複数のプロジェクトを格納するなら、各プロジェクトはそれ自身のsettingを持たなければならない。 つまり、キーはプロジェクトによってスコープされるわけだ。
プロジェクト軸は、「全体ビルド」に設定されることもある。このとき、settingは個々のプロジェクトではなく、全体ビルドに適用される。 ビルドレベルsettingは、しばしばプロジェクト特有のsettingの無いときのフォールバックとして使用される。
コンフィギュレーション軸によるスコープ
コンフィギュレーションはビルドの「フレーバー」を定義する。 多くは、それ自身のクラスパス、ソース、生成パッケージ等を持つ。 コンフィギュレーションという概念はIvyから借りてきている which sbt uses for managed dependencies, and from MavenScopes.
sbtにあるコンフィギュレーションの一部としては以下だ。
- Compileはメインビルドを定義する(src/main/scala).
- Testはテストノビルド方法を定義する(src/test/scala).
- Runtimeはrun taskのためのクラスパスを定義する
コンパイル、パッケージング、実行に関連するキーは、デフォルトではコンフィギュレーションにスコープ付されており、それぞれのコンフィギュレーションで異なる働きをする。 最も明らかな例としては、compile,package,runというタスクキーだが、これらに影響を与えるキー（source-directories、scalac-options、full-classpathなど） もまたコンフィギュレーションにスコープ付されている。
タスク軸によるスコープ
settingはタスクの働きに影響を与えることがある。例えば、packag-optionsというsettingはpackage-srcタスクに影響を与える。
これを実現するため、タスクキー(package-srcのような）は別のキー（package-optionのような）のスコープになるようにしてある。
パッケージビルドのためのタスク(package-src, package-bin, package-doc)は関連するパッケージングに関するキー、つまりartifact-namやpackag-optionsを共有できるが、これらのキーは各パッケージタスクで異なる値を持つこともできる。
グローバルスコープ
各スコープ軸は、その軸タイプのインスタンスを代入しうるが（例えば、タスク軸はタスクを代入しうる）、軸には特別な値Globalを代入することもできる。
Globalはその名の通りの働きだ。settingの値は、その軸のすべてのインスタンスについて適用される。例えば、タスク軸がGlobalの場合、settingは全タスクに適用される。
委譲
スコープ付きキーは、そのスコープに対応する値を持たなければ未定義となる。
それぞれのスコープについて、sbtは、他のスコープからなるフォールバックサーチパスを持つ。 典型的には、キーが特化的なキーについて関連づけされた値を持たないのであれば、より一般的なスコープからそれを取得しようとする。 これにはGlobalスコープや全体ビルドスコープがある。
この機能により、一般的なスコープについての値を設定しておけば、複数のより特化したスコープにそれを継承させることができるんだ。
inpectコマンドを使用して、フォールバックサーチパスあるいは「委譲」を調べることができる。 これを以下に述べるので読み進めて欲しい。
sbt実行時のスコープ付キーの参照
コマンドラインや対話モードにおいて、sbtはスコープ付キーを以下のように表示（あるいは解析）する
{<build-uri>}<project-id>/config:key(for task-key){<build-uri>}<project-id> はプロジェクト軸を指定する。プロジェクト軸が全体ビルドスコープの場合には、<project-id>パートは存在しない
- configはコンフィギュレーション軸を指定する
- (for task-key)はタスク軸を指定する
- keyはスコープ付されるキーを指定する
「*」はどの軸にも指定することができ、これはGlobalスコープを表す。
もしスコープ付キーのパートを省略した場合、それらは以下のように推測される。
- プロジェクトを省略すると、「現在のプロジェクト」が使用される。
- コンフィギュレーションを省略すると、キー依存コンフィギュレーションが自動検出される。
- タスクを省略すると、Globalタスクスコープが使用される。
詳細については「Inspecting Settings」を参照のこと。
スコープ付キーの記述例
- full-classpath キーのみなのでデフォルトスコープが使用される。つまり、現在のプロジェクト、キー依存のコンフィギュレーション、グローバルタスクスコープだ。
- test:full-classpath コンフィギュレーションが指定されているので、testコンフィギュレーションにおけるfull-classpathになる。他の二つのスコープ軸はデフォルトだ。
- *:full-classpath コンフィギュレーションについてGlobalを指定している。
- full-classpath(for doc) docタスクにスコープ付されたfull-classpathを指定している。プロジェクトとコンフィギュレーションについてはデフォルトだ。
{file:/home/hp/checkout/hello/}default-aea33a/test:full-classpath specifies a project, {file:/home/hp/checkout/hello/}default-aea33a, where the project is identified with the build {file:/home/hp/checkout/hello/} and then a project id inside that build default-aea33a. Also specifies configuration test, but leaves the default task axis.
{file:/home/hp/checkout/hello/}/test:full-classpath sets the project axis to "entire build" where the build is {file:/home/hp/checkout/hello/}
{.}/test:full-classpath sets the project axis to "entire build" where the build is {.}. {.} can be written ThisBuild in Scala code.
{file:/home/hp/checkout/hello/}/compile:full-classpath(for doc) sets all three scope axes.
スコープの調査
対話モードでinspectコマンドを使うことにより、キーとそのスコープを調査することができる。 test:full-classpathをinspectしてみよう。
$ sbt
> inspect test:full-classpath
[info] Task: scala.collection.Seq[sbt.Attributed[java.io.File]]
[info] Description:
[info] The exported classpath, consisting of build products and unmanaged and managed, internal and external dependencies.
[info] Provided by:
[info] {file:/home/hp/checkout/hello/}default-aea33a/test:full-classpath
[info] Dependencies:
[info] test:exported-products
[info] test:dependency-classpath
[info] Reverse dependencies:
[info] test:run-main
[info] test:run
[info] test:test-loader
[info] test:console
[info] Delegates:
[info] test:full-classpath
[info] runtime:full-classpath
[info] compile:full-classpath
[info] *:full-classpath
[info] {.}/test:full-classpath
[info] {.}/runtime:full-classpath
[info] {.}/compile:full-classpath
[info] {.}/*:full-classpath
[info] */test:full-classpath
[info] */runtime:full-classpath
[info] */compile:full-classpath
[info] */*:full-classpath
[info] Related:
[info] compile:full-classpath
[info] compile:full-classpath(for doc)
[info] test:full-classpath(for doc)
[info] runtime:full-classpath最初の行は、これがタスクであることを示している（「.sbt build definition」で説明したようにsettingではない）。 また、タスクの結果値が「scala.collection.Seq[sbt.Attributed[java.io.File]]」というタイプであることを示している。
"Provided by"はこの値を定義するスコープ付キーを示している。 この場合には
{file:/home/hp/checkout/hello/}default-aea33a/test:full-classpathになるが、「test」コンフィギュレーションスコープと「{file:/home/hp/checkout/hello/}default-aea33a」というプロジェクトスコープが付いている。
"Dependencies"についてはまだ説明していない。チャンネルはそのままだよ。
委譲(delegates）も表示されている。値が定義されていなければ、sbtは以下を検索する。
- two other configurations (runtime:full-classpath, compile:full-classpath). In these scoped keys, the project is unspecified meaning "current project" and the task is unspecified meaning Global
- configuration set to Global (*:full-classpath), since project is still unspecified it's "current project" and task is still unspecified so Global
project set to {.} or ThisBuild (meaning the entire build, no specific project)
- project axis set to Global (*/test:full-classpath) (remember, an unspecified project means current, so searching Global here is new; i.e. * and "no project shown" are different for the project axis; i.e. */test:full-classpath is not the same as test:full-classpath)
- both project and configuration set to Global (*/*:full-classpath) (remember that unspecified task means Global already, so */*:full-classpath uses Global for all three axes)
（上記の例のinspect test:full-classpathとは異なる）「inspect full-classpath」を実行して、違いを確認してみよう。 コンフィギュレーションが省略されているが、compileであると自動推論される。 したがって、「inspect compile:full-classpath」と入力しても同じ結果が現れる。
さらに「inspect *:full-classpath」としてみよう。 full-classpathはデフォルトではGlobalコンフィギュレーションでは定義されていない。
さらなる詳細は「Inspecting Settings」を参照して欲しい
ビルド定義中でのスコープの参照
build.sbt中において、裸のキーでsettingを作成すると、それは現在のプロジェクトにスコープされ、コンフィギュレーション及びタスクはGlobalになる。
name := "hello"
sbtを起動してnameをinspectし、そのProvided byを見てみよう。
{file:/home/hp/checkout/hello/}default-aea33a/*:nameとなるが、これはプロジェクトが「{file:/home/hp/checkout/hello/}default-aea33a」であり、コンフィギュレーションが「*」つまりGlobalであり、タスクは示されていない（これもGlobalを意味する）。
build.sbtは常に単一プロジェクトのsettingしか定義しない。したがって、「現在のプロジェクト」とは、そのbuild.sbtの存在するプロジェクトのことだ。 （マルチプロジェクトビルドでは、それぞれのプロジェクトはそれ自身のbuild.sbtを持つ）。
キーは「in」というオーバロードされたメソッドを持ち、これはスコープを設定する。 inの引数には、どのスコープ軸のインスタンスをも与えることができる。 例えば、こんなことはしないと思うけど、Compileコンフィギュレーションスコープを指定してnameを設定することができる。
name in Compile := "hello"
あるいは、package-binタスクのスコープをつけることもできる（意味が無い！ただの例だよ）。
name in packageBin := "hello"
あるいは、複数のスコープ軸をつけることができる。例えばpackageBinタスクとCompileコンフィギュレーションにするには、
name in (Compile, packageBin) := "hello"
すべての軸についてGlobalにするには、
name in Global := "hello"
（「name in Global」は暗黙的にすべての軸をGlobalにする。タスクとコンフィゆレーションは既にGlobalだからだ。 だから、「*/*:name」になる。「{file:/home/hp/checkout/hello/}default-aea33a/*:name」ではなく）。
もしScalaを使ったことが無いのなら覚えておこう。 「in」や「:=」はただのメソッドであって、マジックではないことを理解するのは重要だ。 Scalaはそれらのナイスな書き方を許しているのだが、Javaスタイルにすることも可能だ。
name.in(Compile).:=("hello")醜い書き方をする必要はないが、しかしそれらが確かにメソッドであることはわかるだろう。
スコープをいつ指定するべきか？
キーが通常スコープ付されるものであれば、スコープを指定すべきだ。 例えば、compileタスクは通常Compile及びTestコンフィギュレーションにスコープ付されており、これらのスコープ外では存在しようがない。
compileキーの値を変更するには、「compile in Compile」あるいは「compile in Test」と記述する必要がある。 単に「compile」と記述してしまうと、現在のプロジェクトにスコープ付された新しいcompileタスクを定義してしまうことになり、 コンフィギュレーションにスコープ付された標準的なcompileタスクをオーバライドすることにはならない。
もし"Reference to undefined setting"などというエラーが発生した場合、それはたいていスコープを指定し忘れているか、あるいは間違ったスコープをし指定しているかのどちらかだ。 君のキーは何か他のスコープで定義されているのかもしれない。sbtはエラーメッセージの中で示唆しようとする。"Did you mean compile:compile?"等のメッセージをよく見てみよう。
「名前」がキーのほんの一部でしか無いことを意識しよう。 実際に、すべてのキーは名前とスコープから構成される（しかもスコープは三つの軸からなる）。 言い換えれば「packageOptions in (Compile, packageBin)」という式がキー名称なのだ。 単純には、packageOptionもキー名称なのだが、しかし異なるものだ （もしin無しで使用すれば、スコープは暗黙的に、現在のプロジェクト、Globalコンフィギュレーション、Globalタスクになる）