The Scala plugin extends the Java plugin to add support for Scala projects. It can deal with Scala code, mixed Scala and Java code, and even pure Java code (although we don't necessarily recommend to use it for the latter). The plugin supports joint compilation, which allows to freely mix and match Scala and Java code, with dependencies in both directions. For example, a Scala class can extend a Java class that in turn extends a Scala class. This makes it possible to use the best language for the job, and to rewrite any class in the other language if needed.
To use the Scala plugin, include in your build script:
The Scala plugin adds the following tasks to the project.
Table 25.1. Scala plugin - tasks
Task name | Depends on | Type | Description |
compileScala |
compileJava |
ScalaCompile |
Compiles production Scala source files. |
compileTestScala |
compileTestJava |
ScalaCompile |
Compiles test Scala source files. |
compile |
compile |
ScalaCompile |
Compiles the given source set's Scala source files. |
scaladoc |
- | ScalaDoc |
Generates API documentation for the production Scala source files. |
The Scala plugin adds the following dependencies to tasks added by the Java plugin.
Table 25.2. Scala plugin - additional task dependencies
Task name | Depends on |
classes
|
compileScala
|
testClasses
|
compileTestScala
|
|
compile
|
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.
Table 25.3. Scala plugin - project layout
Directory | Meaning |
src/main/java
|
Production Java source |
src/main/resources
|
Production resources |
src/main/scala
|
Production Scala sources. May also contain Java sources for joint compilation. |
src/test/java
|
Test Java source |
src/test/resources
|
Test resources |
src/test/scala
|
Test Scala sources. May also contain Java sources for joint compilation. |
src/
|
Java source for the given source set |
src/
|
Resources for the given source set |
src/
|
Scala sources for the given source set. May also contain Java sources for joint compilation. |
Scala projects need to add a scala-library
dependency to the appropriate configuration(s). This dependency will then
be used as a compile and runtime dependency for the project's Scala code. It will also be used to infer a scala-compiler
dependency for executing the Scala compiler and Scaladoc tool.
[11]
If Scala is used for production code, the scala-library
dependency should be added to the
compile
configuration:
Example 25.3. Declaring a Scala dependency for production code
build.gradle
repositories {
mavenCentral()
}
dependencies {
compile 'org.scala-lang:scala-library:2.9.1'
}
If Scala is only used for test code, the scala-library
dependency should be added to the testCompile
(but not the compile
)
configuration:
Example 25.4. Declaring a Scala dependency for test code
build.gradle
dependencies {
testCompile "org.scala-lang:scala-library:2.9.2"
}
In earlier Gradle versions, it was necessary to add a scala-compiler
dependency to the scalaTools
configuration. Although typically no longer necessary (because the compiler dependency is inferred), this is still supported for
backwards compatibility.
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 Section 21.3, “Conventions”).
Table 25.4. Scala plugin - source set properties
Property name | Type | Default value | Description |
scala
|
SourceDirectorySet (read-only)
|
Not null |
The Scala source files of this source set. Contains all .scala and
.java files found in the Scala source directories, and excludes all other
types of files.
|
scala.srcDirs
|
Set<File> . Can set using anything described in Section 16.5, “Specifying a set of input files”.
|
[
|
The source directories containing the Scala source files of this source set. May also contain Java source files for joint compilation. |
allScala
|
FileTree (read-only)
|
Not null |
All Scala source files of this source set. Contains only the .scala files
found in the Scala source directories.
|
These convention properties are provided by a convention object of type ScalaSourceSet
.
The Scala plugin also modifies some source set properties:
Table 25.5. Scala plugin - source set properties
Property name | Change |
allJava
|
Adds all .java files found in the Scala source directories. |
allSource
|
Adds all source files found in the Scala source directories. |
The Scala plugin includes support for fsc,
the Fast Scala Compiler. fsc
runs in a separate daemon process and can speed up
compilation significantly.
Example 25.5. Enabling the Fast Scala Compiler
build.gradle
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.
When scalaCompileOptions.fork
is set to true
, compilation will take place
in an external process. The details of forking depend on which compiler is used. The Ant based compiler
(scalaCompileOptions.useAnt = true
) will fork a new process for every 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.
Memory settings for the external process default to the JVM's defaults. To adjust memory settings,
configure scalaCompileOptions.forkOptions
as needed:
Example 25.6. Adjusting memory settings
build.gradle
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.
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
:
Example 25.7. Activating the Zinc based compiler
build.gradle
tasks.withType(ScalaCompile) { scalaCompileOptions.useAnt = false }
Except where noted in theAPI 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.
The Scala plugin adds a configuration named zinc
to resolve the Zinc library and its dependencies. To override the
Zinc version that Gradle uses by default, add an explicit Zinc dependency (for example zinc "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.
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.
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, 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.
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.
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.