Please enter your password of your account at the remote wiki below.
/!\ You should trust both wikis because the password could be read by the particular administrators.

Clear message
Locked History Actions

sbt/Getting-Started-Scopes

スコープ

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タスクになる)

次はSettingについてもっと