第25章 Scalaプラグイン

To use the Scala plugin, include the following in your build script:

Scalaプラグインを使うには、ビルドスクリプトに以下の行を追加します。

apply plugin: 'scala'

The Scala plugin adds the following tasks to the project.

Scalaプラグインは、プロジェクトに以下のタスクを追加します。

The Scala plugin adds the following dependencies to tasks added by the Java plugin.

Scalaプラグインは、Javaプラグインによって追加されたタスクに以下の依存関係を追加します。

図25.1 Scalaプラグイン - タスクScala plugin - tasks

The Scala plugin assumes the project layout shown below. All the Scala source directories can contain Scala and Java code. The Java source directories may only contain Java source code. None of these directories need to exist or have anything in them; the Scala plugin will simply compile whatever it finds.

Scalaプラグインは次のようなプロジェクトレイアウトを想定しています。 すべてのScalaソースディレクトリにはScalaだけでなくJavaコードも含めることができますが、JavaソースディレクトリにはJavaコードしか含めることができません。 また、これらのどのディレクトリも、存在しなかったり、何も含んでいなくてもかまいません。Scalaプラグインは、単純に見つけたディレクトリをコンパイルするだけです。

sourceSets {
    main {
        scala {
            srcDirs = ['src/scala']
        }
    }
    test {
        scala {
            srcDirs = ['test/scala']
        }
    }
}

Scala projects need to declare a scala-library dependency. This dependency will then be used on compile and runtime class paths. It will also be used to get hold of the Scala compiler and Scaladoc tool, respectively. Scalaプロジェクトでは、scala-libraryへの依存関係を宣言する必要があります。 この依存関係は、Scalaコードをコンパイルしたり実行したりする際のクラスパスに追加されるほか、ScalaコンパイラおよびScaladocツールを取得する際にも使用されます。 ^[20]

If Scala is used for production code, the scala-library dependency should be added to the compile configuration:

Scalaが製品コードで使われている場合は、scala-libraryへの依存関係はcompileコンフィグレーションに追加してください。

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.scala-lang:scala-library:2.11.1'
}

If Scala is only used for test code, the scala-library dependency should be added to the testCompile configuration:

Scalaがテストコードのみで使われている場合は、scala-libraryへの依存関係はtestCompileコンフィグレーションに追加してください。

dependencies {
    testCompile "org.scala-lang:scala-library:2.11.1"
}

The ScalaCompile and ScalaDoc tasks consume Scala code in two ways: on their classpath, and on their scalaClasspath. The former is used to locate classes referenced by the source code, and will typically contain scala-library along with other libraries. The latter is used to load and execute the Scala compiler and Scaladoc tool, respectively, and should only contain the scala-compiler library and its dependencies.

ScalaCompileタスクとScalaDocタスクは二つの用途でScalaを使用します。タスクのclasspathとscalaClasspathです。前者はソースコードから参照されているクラスを配置するパスで、scala-libraryも典型的には他のライブラリと一緒に格納されます。後者はScalaコンパイラとScaladocツールをロードして実行するために使用されるパスで、scala-compilerライブラリとその依存関係のみが配置されていなければなりません。

Unless a task's scalaClasspath is configured explicitly, the Scala (base) plugin will try to infer it from the task's classpath. This is done as follows: scalaClasspathが明示的に設定されていない場合、Scala(base)プラグインはタスクのclasspathから以下のように設定値を推論しようとします。

The Scala plugin does not add any convention properties to the project.

Scalaプラグインは、プロジェクトに規約プロパティを追加しません。

The Scala plugin adds the following convention properties to each source set in the project. You can use these properties in your build script as though they were properties of the source set object (see 「規約 Conventions」).

Scalaプロジェクトの各ソースセットに以下の規約プロパティを追加します。これらのプロパティは、あたかもソースセットオブジェクトのプロパティであるかのようにビルドスクリプト内で使うことができます（「規約 Conventions」参照）

These convention properties are provided by a convention object of type ScalaSourceSet.

これらの規約プロパティはScalaSourceSet型の規約オブジェクトにより提供されます。

The Scala plugin also modifies some source set properties:

また、Scalaプラグインはいくつかのソースセットプロパティを修正します。

The Scala plugin includes support for fsc, the Fast Scala Compiler. fsc runs in a separate daemon process and can speed up compilation significantly. Scalaプラグインには、fsc、Fast Scala Compilerのサポートが含まれています。

compileScala {
    scalaCompileOptions.useCompileDaemon = true

    // optionally specify host and port of the daemon:
    scalaCompileOptions.daemonServer = "localhost:4243"
}

Note that fsc expects to be restarted whenever the contents of its compile class path change. (It does detect changes to the compile class path itself.) This makes it less suitable for multi-project builds. ただし、次の点に注意してください。fscは、コンパイル時のクラスパスに含まれるもの（訳注：jarなど）が変更される度に再起動させる必要があります。（コンパイル時クラスパス自体の変更は検知されますが）。 このため、マルチプロジェクトとの相性は悪くなります。

When scalaCompileOptions.fork is set to true, compilation will take place in an external process. The Ant based compiler (scalaCompileOptions.useAnt = true) will fork a new process for every invocation of the ScalaCompile task, and does not fork by default. The Zinc based compiler (scalaCompileOptions.useAnt = false) will leverage the Gradle compiler daemon, and does so by default.

scalaCompileOptions.forkオプションがtrueにセットされていると、コンパイル処理は外部プロセスで実行されます。 フォーク処理の詳細はどのコンパイラを使用するかにより異なり、Antベースのコンパイラを使用する場合は（scalaCompileOptions.useAnt = true）、ScalaCompileタスクが実行される度に新しいプロセスがフォークされます。また、デフォルトではフォークされません。 Zincベースのコンパイラを使う場合（scalaCompileOptions.useAnt = false）、Gradleのコンパイラデーモンを使用してコンパイルされます。Antベースのコンパイラと異なり、こちらがデフォルトの処理です。

Memory settings for the external process default to defaults of the JVM. To adjust memory settings, configure the scalaCompileOptions.forkOptions property as needed: 外部プロセスのメモリ設定は、デフォルトではJVMのデフォルト値が使用されます。メモリ設定を調整するには、scalaCompileOptions.forkOptionsを必要に応じて設定してください。

tasks.withType(ScalaCompile) {
    configure(scalaCompileOptions.forkOptions) {
        memoryMaximumSize = '1g'
        jvmArgs = ['-XX:MaxPermSize=512m']
    }
}

By compiling only classes whose source code has changed since the previous compilation, and classes affected by these changes, incremental compilation can significantly reduce Scala compilation time. It is particularly effective when frequently compiling small code increments, as is often done at development time.

前回コンパイルしたときからの変更差分、およびそれにより影響を受けるクラスのみを再コンパイルすることで、Scalaのコンパイル時間を大幅に減らすことができます。 これは、コードを小さく変更して頻繁にコンパイルするようなとき、開発中にはしばしばそういうことがありますが、そのような場面では特に有用です。

The Scala plugin now supports incremental compilation by integrating with Zinc, a standalone version of sbt's incremental Scala compiler. To switch the ScalaCompile task from the default Ant based compiler to the new Zinc based compiler, set scalaCompileOptions.useAnt to false: Scalaプラグインは、Zincという、sbtのインクリメンタルScalaコンパイラのスタンドアローン版を統合することでインクリメンタルコンパイルをサポートしています。

tasks.withType(ScalaCompile) {
    scalaCompileOptions.useAnt = false
}

Except where noted in the API documentation, the Zinc based compiler supports exactly the same configuration options as the Ant based compiler. Note, however, that the Zinc compiler requires Java 6 or higher to run. This means that Gradle itself has to be run with Java 6 or higher.

APIドキュメントに記載されている部分を除き、ZincベースのコンパイラはAntベースのコンパイラと全く同じ設定オプションをサポートします。 ただ、ZincコンパイラはJava6以上のバージョンを必要とするので注意してください。これは、Gradle自身もJava6以上で動かさなくてはならないことを意味します。

The Scala plugin adds a configuration named zinc to resolve the Zinc library and its dependencies. Gradle will have a default version of the Zinc library, but if you want to override the Zinc version that Gradle uses, add an explicit dependency like “com.typesafe.zinc:zinc:0.1.4”. Regardless of which Zinc version is used, Zinc will always use the Scala compiler found on the scalaTools configuration.

Scalaプラグインは、zincという名前のコンフィグレーションを追加し、Zincライブラリとその依存関係を解決するために使用します。 Gradleがデフォルトで使用するZincのバージョンをオーバーライドするには、Zincへの依存関係（例えば、zinc "com.typesafe.zinc:zinc:0.1.4"）を明示的に指定してください。 どのバージョンのZincが使用されているかにかかわらず、Zincは常にscalaToolsコンフィグレーションに含まれるScalaコンパイラを使用します。

Just like Gradle's Ant based compiler, the Zinc based compiler supports joint compilation of Java and Scala code. By default, all Java and Scala code under src/main/scala will participate in joint compilation. With the Zinc based compiler, even Java code will be compiled incrementally.

Antベースのコンパイラ同様、ZincベースのコンパイラもJavaとScalaのジョイントコンパイルをサポートします。 デフォルトでは、src/main/scalaにある全てのJavaとScalaのコードがジョイントコンパイルに使用されます。Zincベースのコンパイラは、たとえJavaコードでもインクリメンタルにコンパイルできます。

Incremental compilation requires dependency analysis of the source code. The results of this analysis are stored in the file designated by scalaCompileOptions.incrementalOptions.analysisFile (which has a sensible default). In a multi-project build, analysis files are passed on to downstream ScalaCompile tasks to enable incremental compilation across project boundaries. For ScalaCompile tasks added by the Scala plugin, no configuration is necessary to make this work. For other ScalaCompile tasks that you might add, the property scalaCompileOptions.incrementalOptions.publishedCode needs to be configured to point to the classes folder or Jar archive by which the code is passed on to compile class paths of downstream ScalaCompile tasks. Note that if publishedCode is not set correctly, downstream tasks may not recompile code affected by upstream changes, leading to incorrect compilation results.

インクリメンタルコンパイルを行うには、ソースコードを解析する必要があります。解析結果は、scalaCompileOptions.incrementalOptions.analysisFile（適切なデフォルト値が設定されています）で指定されたファイルに保存されます。 マルチプロジェクトの場合、この解析ファイルは下流のScalaCompileタスクに渡されるので、プロジェクトをまたいでのインクリメンタルコンパイルが可能です。 Scalaプラグインにより追加されたScalaCompileタスクはデフォルトでそのように動作するので、追加の設定は必要ありません。 その他のScalaCompileタスクでこの動作を有効にするには、scalaCompileOptions.incrementalOptions.publishedCodeが適切なクラスフォルダやJarアーカイブを指すように設定し、下流のタスクのコンパイルクラスパスにコードを渡す必要があります。 publishedCodeが正しく設定されていない場合、上流のソースが変更されても下流のタスクの再コンパイルが適切に動かず、コンパイル結果も正しくなりませんので注意してください。

Due to the overhead of dependency analysis, a clean compilation or a compilation after a larger code change may take longer than with the Ant based compiler. For CI builds and release builds, we currently recommend to use the Ant based compiler.

解析処理に伴うオーバーヘッドにより、クリーンコンパイルや大規模な変更を行った後のコンパイルは、Antベースのコンパイラより長い時間を要するかもしれません。インテグレーションサーバーでのビルドやリリースビルドの際は、今のところAntベースのコンパイラを推奨します。

Note that Zinc's Nailgun based daemon mode is not supported. Instead, we plan to enhance Gradle's own compiler daemon to stay alive across Gradle invocations, reusing the same Scala compiler. This is expected to yield another significant speedup for Scala compilation.

ZincのNailgunベースのデーモンモードには対応していません。代わりに、Gradle自身のコンパイラデーモンを拡張し、Gradle実行間で同じScalaコンパイラを再利用できるようにする予定です。デーモンモードにより、Scalaコンパイルが更にスピードアップすることが期待されます。

When the Eclipse plugin encounters a Scala project, it adds additional configuration to make the project work with Scala IDE out of the box. Specifically, the plugin adds a Scala nature and dependency container.

When the IDEA plugin encounters a Scala project, it adds additional configuration to make the project work with IDEA out of the box. Specifically, the plugin adds a Scala facet and a Scala compiler library that matches the Scala version on the project's class path.