Revision 7 as of 2011-10-29 04:36:12

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」を参照のこと。

スコープ付キーの記述例

スコープの調査

対話モードで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" points you to the scoped key that defines the value, in this case {file:/home/hp/checkout/hello/}default-aea33a/test:full-classpath (which is the full-classpath key scoped to the test configuration and the {file:/home/hp/checkout/hello/}default-aea33a project).

"Dependencies"についてはまだ説明していない。チャンネルはそのままだよ。

You can also see the delegates; if the value were not defined, sbt would search through:

  • 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)

Try inspect full-classpath (as opposed to the above example, inspect test:full-classpath) to get a sense of the difference. Because the configuration is omitted, it is autodetected as compile. inspect compile:full-classpath should therefore look the same as inspect full-classpath.

Try inspect *:full-classpath for another contrast. full-classpath is not defined in the Global configuration by default.

Again, for more details, see Inspecting Settings. Referring to scopes in a build definition

If you create a setting in build.sbt with a bare key, it will be scoped to the current project, configuration Global and task Global:

name := "hello"

Run sbt and inspect name to see that it's provided by {file:/home/hp/checkout/hello/}default-aea33a/*:name, that is, the project is {file:/home/hp/checkout/hello/}default-aea33a, the configuration is * (meaning global), and the task is not shown (which also means global).

build.sbt always defines settings for a single project, so the "current project" is the project you're defining in that particular build.sbt. (For multi-project builds, each project has its own build.sbt.)

Keys have an overloaded method called in used to set the scope. The argument to in can be an instance of any of the scope axes. So for example, though there's no real reason to do this, you could set the name scoped to the Compile configuration:

name in Compile := "hello"

or you could set the name scoped to the package-bin task (pointless! just an example):

name in packageBin := "hello"

or you could set the name with multiple scope axes, for example in the packageBin task in the Compile configuration:

name in (Compile, packageBin) := "hello"

or you could use Global for all axes:

name in Global := "hello"

(name in Global implicitly converts the scope axis Global to a scope with all axes set to Global; the task and configuration are already Global by default, so here the effect is to make the project Global, that is, define */*:name rather than {file:/home/hp/checkout/hello/}default-aea33a/*:name)

If you aren't used to Scala, a reminder: it's important to understand that in and := are just methods, not magic. Scala lets you write them in a nicer way, but you could also use the Java style:

name.in(Compile).:=("hello")

There's no reason to use this ugly syntax, but it illustrates that these are in fact methods.

When to specify a scope

You need to specify the scope if the key in question is normally scoped. For example, the compile task, by default, is scoped to Compile and Test configurations, and does not exist outside of those scopes.

To change the value associated with the compile key, you need to write compile in Compile or compile in Test. Using plain compile would define a new compile task scoped to the current project, rather than overriding the standard compile tasks which are scoped to a configuration.

If you get an error like "Reference to undefined setting", often you've failed to specify a scope, or you've specified the wrong scope. The key you're using may be defined in some other scope. sbt will try to suggest what you meant as part of the error message; look for "Did you mean compile:compile?"

One way to think of it is that a name is only part of a key. In reality, all keys consist of both a name, and a scope (where the scope has three axes). The entire expression packageOptions in (Compile, packageBin) is a key name, in other words. Simply packageOptions is also a key name, but a different one (for keys with no in, a scope is implicitly assumed: current project, global config, global task).