The Scala Plugin

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 you 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.

Usage

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

Example 1. Using the Scala plugin

GroovyKotlin

build.gradle

plugins {
    id 'scala'
}

Tasks

The Scala plugin adds the following tasks to the project.

compileScala — ScalaCompile: Depends on: compileJava

Compiles production Scala source files.
compileTestScala — ScalaCompile: Depends on: compileTestJava

Compiles test Scala source files.
compileSourceSetScala — ScalaCompile: Depends on: compileSourceSetJava

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 1. Scala plugin - additional task dependencies
Task name	Depends on
`classes`	`compileScala`
`testClasses`	`compileTestScala`
`sourceSetClasses`	`compileSourceSetScala`

Figure 1. Scala plugin - tasks

Project layout

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.

src/main/java: Production Java source.
src/main/resources: Production resources, such as XML and properties files.
src/main/scala: Production Scala source. May also contain Java source files for joint compilation.

src/test/java: Test Java source.
src/test/resources: Test resources.
src/test/scala: Test Scala source. May also contain Java source files for joint compilation.

src/sourceSet/java: Java source for the source set named sourceSet.
src/sourceSet/resources: Resources for the source set named sourceSet.
src/sourceSet/scala: Scala source files for the given source set. May also contain Java source files for joint compilation.

Changing the project layout

Just like the Java plugin, the Scala plugin allows you to configure custom locations for Scala production and test source files.

Example 2. Custom Scala source layout

GroovyKotlin

build.gradle

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

build.gradle.kts

sourceSets {
    main {
        withConvention(ScalaSourceSet::class) {
            scala {
                setSrcDirs(listOf("src/scala"))
            }
        }
    }
    test {
        withConvention(ScalaSourceSet::class) {
            scala {
                setSrcDirs(listOf("test/scala"))
            }
        }
    }
}

Dependency management

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.^[1]

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

Example 3. Declaring a Scala dependency for production code

GroovyKotlin

build.gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.scala-lang:scala-library:2.11.12'
    testImplementation 'org.scalatest:scalatest_2.11:3.0.0'
    testImplementation 'junit:junit:4.12'
}

build.gradle.kts

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.scala-lang:scala-library:2.11.12")
    testImplementation("org.scalatest:scalatest_2.11:3.0.0")
    testImplementation("junit:junit:4.12")
}

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

Example 4. Declaring a Scala dependency for test code

GroovyKotlin

build.gradle

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

Automatic configuration of scalaClasspath

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.

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:

If a scala-library jar is found on classpath, and the project has at least one repository declared, a corresponding scala-compiler repository dependency will be added to scalaClasspath.
Otherwise, execution of the task will fail with a message saying that scalaClasspath could not be inferred.

Configuring the Zinc compiler

The Scala plugin uses a configuration named zinc to resolve the Zinc compiler and its dependencies. Gradle will provide a default version of Zinc, but if you need to use a particular Zinc version, you can add an explicit dependency like “com.typesafe.zinc:zinc:0.3.6” to the zinc configuration. Gradle supports version 0.3.0 of Zinc and above; however, due to a regression in the Zinc compiler, versions 0.3.2 through 0.3.5.2 cannot be used.

Example 5. Declaring a version of the Zinc compiler to use

GroovyKotlin

build.gradle

dependencies {
    zinc 'com.typesafe.zinc:zinc:0.3.9'
}

It is important to take care when declaring your scala-library dependency. The Zinc compiler itself needs a compatible version of scala-library that may be different from the version required by your application. Gradle takes care of adding a compatible version of scala-library for you, but over-broad dependency resolution rules could force an incompatible version to be used instead.

For example, using configurations.all to force a particular version of scala-library would also override the version used by the Zinc compiler:

Example 6. Forcing a scala-library dependency for all configurations

GroovyKotlin

build.gradle

configurations.all {
    resolutionStrategy.force "org.scala-lang:scala-library:2.11.12"
}

The best way to avoid this problem is to be more selective when configuring the scala-library dependency (such as not using a configuration.all rule or using a conditional to prevent the rule from being applied to the zinc configuration). Sometimes this rule may come from a plugin or other code that you do not have control over. In such a case, you can force a correct version of the library on the zinc configuration only:

Example 7. Forcing a scala-library dependency for the zinc configuration

GroovyKotlin

build.gradle

configurations.zinc {
    resolutionStrategy.force "org.scala-lang:scala-library:2.10.5"
}

You can diagnose problems with the version of the Zinc compiler selected by running dependencyInsight for the zinc configuration.

Convention properties

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

Source set properties

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.

scala — SourceDirectorySet (read-only): 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. Default value: non-null.
scala.srcDirs — Set<File>: The source directories containing the Scala source files of this source set. May also contain Java source files for joint compilation. Can set using anything described in Understanding implicit conversion to file collections. Default value: [projectDir/src/name/scala].
allScala — FileTree (read-only): All Scala source files of this source set. Contains only the .scala files found in the Scala source directories. Default value: non-null.

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

The Scala plugin also modifies some source set properties:

Table 2. 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.

Compiling in external process

Scala compilation takes place in an external process.

Memory settings for the external process default to the defaults of the JVM. To adjust memory settings, configure the scalaCompileOptions.forkOptions property as needed:

Example 8. Adjusting memory settings

GroovyKotlin

build.gradle

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

build.gradle.kts

tasks.withType<ScalaCompile>().configureEach {
    scalaCompileOptions.forkOptions.apply {
        memoryMaximumSize = "1g"
        jvmArgs = listOf("-XX:MaxPermSize=512m")
    }
}

Incremental compilation

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 defaults to incremental compilation by integrating with Zinc, a standalone version of sbt's incremental Scala compiler. If you want to disable the incremental compilation, set force = true in your build file:

Example 9. Forcing all code to be compiled

GroovyKotlin

build.gradle

tasks.withType(ScalaCompile) {
    scalaCompileOptions.with {
        force = true
    }
}

Note: This will only cause all classes to be recompiled if at least one input source file has changed. If there are no changes to the source files, the compileScala task will still be considered UP-TO-DATE as usual.

The Zinc-based Scala 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. 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 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.

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.

Compiling and testing for Java 6 or Java 7

The Scala compiler ignores Gradle’s targetCompatibility and sourceCompatibility settings. In Scala 2.11, the Scala compiler always compiles to Java 6 compatible bytecode. In Scala 2.12, the Scala compiler always compiles to Java 8 compatible bytecode. If you also have Java source, you can follow the same steps as for the Java plugin to ensure the correct Java compiler is used.

gradle.properties

# in $HOME/.gradle/gradle.properties
java6Home=/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home

GroovyKotlin

build.gradle

java {
    sourceCompatibility = JavaVersion.VERSION_1_6
}

assert hasProperty('java6Home') : "Set the property 'java6Home' in your your gradle.properties pointing to a Java 6 installation"
def javaExecutablesPath = new File(java6Home, 'bin')
def javaExecutables = [:].withDefault { execName ->
    def executable = new File(javaExecutablesPath, execName)
    assert executable.exists() : "There is no ${execName} executable in ${javaExecutablesPath}"
    executable
}

tasks.withType(AbstractCompile) {
    options.with {
        fork = true
        forkOptions.javaHome = file(java6Home)
    }
}
tasks.withType(Test) {
    executable = javaExecutables.java
}
tasks.withType(JavaExec) {
    executable = javaExecutables.java
}
tasks.withType(Javadoc) {
    executable = javaExecutables.javadoc
}

build.gradle.kts

java {
    sourceCompatibility = JavaVersion.VERSION_1_6
}

require(hasProperty("java6Home")) { "Set the property 'java6Home' in your your gradle.properties pointing to a Java 6 installation" }
val java6Home: String by project
val javaExecutablesPath = File(java6Home, "bin")
fun javaExecutable(execName: String): String {
    val executable = File(javaExecutablesPath, execName)
    require(executable.exists()) { "There is no ${execName} executable in ${javaExecutablesPath}" }
    return executable.toString()
}

tasks.withType<ScalaCompile>().configureEach {
    options.apply {
        isFork = true
        forkOptions.javaHome = file(java6Home)
    }
}
tasks.withType<Test>().configureEach {
    executable = javaExecutable("java")
}
tasks.withType<JavaExec>().configureEach {
    executable = javaExecutable("java")
}
tasks.withType<Javadoc>().configureEach {
    executable = javaExecutable("javadoc")
}

Eclipse Integration

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.

IntelliJ IDEA Integration

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 SDK (IntelliJ IDEA 14+) and a Scala compiler library that matches the Scala version on the project’s class path. The Scala plugin is backwards compatible with earlier versions of IntelliJ IDEA and it is possible to add a Scala facet instead of the default Scala SDK by configuring targetVersion on IdeaModel.

Example 10. Explicitly specify a target IntelliJ IDEA version

GroovyKotlin

build.gradle

idea {
    targetVersion = '13'
}

1. See Automatic configuration of Scala classpath.