From 6ca9eb520629f03d708d8e4e6d603849302658be Mon Sep 17 00:00:00 2001 From: Louis Jacomet Date: Thu, 16 Feb 2023 15:28:24 +0100 Subject: [PATCH] Document Scala Java bytecode target changes Fixes #21551 --- .../src/docs/userguide/jvm/scala_plugin.adoc | 31 +++++++++++++++++++ .../migration/upgrading_version_7.adoc | 7 +++++ 2 files changed, 38 insertions(+) diff --git a/subprojects/docs/src/docs/userguide/jvm/scala_plugin.adoc b/subprojects/docs/src/docs/userguide/jvm/scala_plugin.adoc index db0ceb60a09d..97ca925988e7 100644 --- a/subprojects/docs/src/docs/userguide/jvm/scala_plugin.adoc +++ b/subprojects/docs/src/docs/userguide/jvm/scala_plugin.adoc @@ -228,6 +228,37 @@ The Scala plugin also modifies some source set properties: | `allSource` | Adds all source files found in the Scala source directories. |=== +[[sec:scala_target]] +== Target bytecode level and Java APIs version + +When running the Scala compile task, Gradle will always add a parameter to configure the Java target for the Scala compiler that is derived from the Gradle configuration: + +* When using toolchains, the `-release` option, or `target` for older Scala versions, is selected, with a version matching the Java language level of the toolchain configured. +* When not using toolchains, Gradle will always pass a `target` flag -- with exact value dependent on the Scala version -- to compile to Java 8 bytecode. + +[NOTE] +==== +This means that using toolchains with a recent Java version and an old Scala version can result in failures because Scala only supported Java 8 bytecode for some time. +The solution is then to either use the right Java version in the toolchain or explicitly downgrade the target when needed. +==== + +The following table explains the values computed by Gradle: + +.Scala target parameter based on project configuration +[%header%autowidth,compact] +|=== +| Scala version | Toolchain in use | Parameter value +.2+| version < `2.13.1` | yes | `-target:jvm-1.` + | no | `-target:jvm-1.8` +.2+| `2.13.1` \<= version < `2.13.9` | yes | `-target:` + | no | `-target:8` +.2+| `2.13.9` \<= version < `3.0` | yes | `-release:` + | no | `-target:8` +.2+| `3.0` \<= version | yes | `-release:` + | no | `-Xtarget:8` +|=== + +Setting any of these flags explicitly, or using flags containing `java-output-version`, on link:{groovyDslPath}/org.gradle.language.scala.tasks.BaseScalaCompileOptions.html#org.gradle.language.scala.tasks.BaseScalaCompileOptions:additionalParameters[`ScalaCompile.scalaCompileOptions.additionalParameters`] disables that logic in favor of the explicit flag. [[sec:scala_compiling_in_external_process]] == Compiling in external process diff --git a/subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc b/subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc index 30c6a33f4770..88767ed5e7b7 100644 --- a/subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc +++ b/subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc @@ -693,6 +693,13 @@ In case no toolchains are explicitly configured, the toolchain corresponding to Similarly, tasks from the Groovy and Scala plugins also rely on toolchains to determine on which JVM they are executed. +==== Scala compilation target + +With the toolchain changes described above, Scala compilation tasks are now always provided with a `target` or `release` parameter. +The exact parameter and value depend on toolchain usage, or not, and Scala version. + +See the <> for details. + [[changes_7.6]] == Upgrading from 7.5 and earlier