Skip to content

Commit 9e069c8

Browse files
SethTisueSethTisue
authored
Merge pull request #3230 from SethTisue/jdk-compat-updates
various updates to JDK compat guide
1 parent fff43fe commit 9e069c8

File tree

1 file changed

+40
-26
lines changed

1 file changed

+40
-26
lines changed

‎_overviews/jdk-compatibility/overview.md‎

Lines changed: 40 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,46 @@ title: JDK Compatibility
44
permalink: /overviews/jdk-compatibility/overview.html
55
---
66

7-
Scala's primary platform is the Java Virtual Machine (JVM). (Other supported platforms: [Scala.js](https://www.scala-js.org/), [Scala Native](https://scala-native.org/).)
7+
Scala's primary platform is the Java Virtual Machine (JVM). Other supported platforms are [Scala.js](https://www.scala-js.org/) and [Scala Native](https://scala-native.org/).
88

99
Sometimes new JVM and JDK (Java Development Kit) versions require us to update Scala to remain compatible.
1010

11-
## Scala compatibility table
11+
## Scala 3 compatibility
1212

13-
Minimum Scala versions:
13+
Scala 3 versions from 3.3 LTS through Scala 3.7 support JDK 8 and above.
1414

15-
| JDK | 3 | 3 LTS | 2.13 | 2.12 | 2.11 |
16-
|:-----------:|:--------:|:--------:|:---------:|:---------:|:----------:|
17-
| 25 (LTS) | 3.7.1 | 3.3.6 | 2.13.17 | 2.12.21* | |
18-
| 21 (LTS) | 3.4.0 | 3.3.1 | 2.13.11 | 2.12.18 | |
19-
| 17 (LTS) | 3.0.0 | 3.3.0 | 2.13.6 | 2.12.15 | |
20-
| 11 (LTS) | 3.0.0 | 3.3.0 | 2.13.0 | 2.12.4 | 2.11.12 |
21-
| 8 (LTS) | 3.0.0 | 3.3.0 | 2.13.0 | 2.12.0 | 2.11.0 |
15+
As per [this blog post](https://www.scala-lang.org/news/next-scala-lts-jdk.html),
16+
Scala 3.8 will have a new minimum JDK version of 17.
17+
18+
The next Scala 3 LTS release will be Scala 3.9.
19+
20+
Minimum Scala 3 versions for each JDK:
21+
22+
| JDK | 3.8* | 3.4+ | 3.3 LTS |
23+
|:-----------:|:------:|:--------:|:--------:|
24+
| 25 (LTS) | 3.8.0* | 3.7.1 | 3.3.6 |
25+
| 21 (LTS) | 3.8.0* | 3.4.0 | 3.3.1 |
26+
| 17 (LTS) | 3.8.0* | 3.4.0 | 3.3.0 |
27+
| 11 (LTS) | | 3.4.0 | 3.3.0 |
28+
| 8 (LTS) | | 3.4.0 | 3.3.0 |
29+
30+
\* = forthcoming; support available in [nightly builds](https://docs.scala-lang.org/overviews/core/nightlies.html)
31+
32+
Even when a version combination isn't listed as supported, most features might still work.
33+
34+
Using the latest patch version of your chosen Scala version line is always recommended.
35+
36+
## Scala 2 compatibility
37+
38+
Minimum Scala 2 versions for each JDK:
39+
40+
| JDK | 2.13 | 2.12 |
41+
|:-----------:|:---------:|:---------:|
42+
| 25 (LTS) | 2.13.17 | 2.12.21* |
43+
| 21 (LTS) | 2.13.11 | 2.12.18 |
44+
| 17 (LTS) | 2.13.6 | 2.12.15 |
45+
| 11 (LTS) | 2.13.0 | 2.12.4 |
46+
| 8 (LTS) | 2.13.0 | 2.12.0 |
2247

2348
\* = forthcoming; support available in [nightly builds](https://docs.scala-lang.org/overviews/core/nightlies.html)
2449

@@ -34,7 +59,7 @@ Minimum working versions:
3459

3560
| JDK | scala-cli | sbt | mill |
3661
|:-----------:|:-----------:|:---------:|:-----------|
37-
| 25 (LTS) | forthcoming | 1.9.0 | 1.0.0 |
62+
| 25 (LTS) | 1.10.0 | 1.9.0 | 1.0.0 |
3863
| 21 (LTS) | 1.0.0 | 1.9.0 | 0.11.5 |
3964
| 17 (LTS) | 1.0.0 | 1.6.0 | 0.7.0 |
4065
| 11 (LTS) | 1.0.0 | 1.1.0 | 0.1.5 |
@@ -50,11 +75,11 @@ Using a different build tool, such as Gradle or Maven? We invite pull requests a
5075

5176
## Running versus compiling
5277

53-
JDK 8, 11, 17, 21, and 25 are all reasonable choices both for *compiling* and *running* Scala code.
78+
JDK 17, 21, and 25 are all good choices both for *compiling* and *running* Scala code.
5479

55-
Since the JVM is normally backwards compatible, it is usually safe to use a newer JVM for *running* your code than the one it was compiled on, especially if you are not using JVM features designated "experimental" or "unsafe".
80+
JDK 8 and 11 are also possible choices. As of 2025, these versions remain in use at some shops, but usage has declined greatly and many projects are dropping support. If you compile on JDK 17+ but want to allow your users to stay on 8, use `--release 8` to avoid using APIs and features that don't exist in 8. Another option is to use a newer JDK for your daily work but do release builds on JDK 8.
5681

57-
JDK 8 remains in use at some shops (as of 2023), but usage is declining and some projects are dropping support. If you compile on JDK 11+ but want to allow your users to stay on 8, additional care is needed to avoid using APIs and features that don't exist in 8. (For this reason, some Scala developers use a newer JDK for their daily work but do release builds on JDK 8.)
82+
Since the JVM is normally backwards compatible, it is usually safe to use a newer JVM for *running* your code than the one it was compiled on, especially if you are not using JVM features designated "experimental" or "unsafe".
5883

5984
As per [this blog post](https://www.scala-lang.org/news/next-scala-lts-jdk.html), Scala 3.8 will have a new minimum JDK version of 17.
6085

@@ -74,15 +99,13 @@ In almost every case, you're free to use the JDK and JVM of your choice.
7499

75100
JDK 8 users typically use the Oracle JDK or some flavor of OpenJDK.
76101

77-
Most JDK 11+ users are using OpenJDK, or GraalVM which runs in the context of OpenJDK. GraalVM performs well on the Scala benchmarks, and it benefits from GraalVM runtime and runs faster too.
78-
79102
OpenJDK comes in various flavors, offered by different providers. We typically build and test Scala using [Temurin](https://adoptium.net) or [Zulu](https://www.azul.com/downloads/), but the differences are unlikely to matter to most users.
80103

81104
## JDK 11 compatibility notes
82105

83106
The Scala test suite and Scala community build are green on JDK 11.
84107

85-
In general, Scala works on JDK 11+, including GraalVM, but may not take special advantage of features that were added after JDK 8.
108+
In general, Scala works on JDK 11+, but may not take special advantage of features that were added after JDK 8.
86109

87110
For example, the Scala compiler does not enforce the restrictions of the Java Platform Module System, which means that code that typechecks may incur linkage errors at runtime. Scala 2.13.x will eventually provide [rudimentary support](https://github.com/scala/scala/pull/7218) for this (perhaps only in nightlies built on JDK 11).
88111

@@ -132,8 +155,6 @@ For information on timing of the forthcoming release, see:
132155

133156
* https://contributors.scala-lang.org/t/scala-2-12-21-release-planning/6753
134157

135-
<!-- TODO For sbt users, sbt 1.9.0 is the first version to support JDK 21.-->
136-
137158
For possible Scala 3 issues, see the [area:jdk](https://github.com/scala/scala3/labels/area%3Ajdk) and [compat:java](https://github.com/scala/scala3/labels/compat%3Ajava) labels in [the Scala 3 issue tracker](https://github.com/scala/scala3/issues).
138159

139160
For possible Scala 2 issues, see the [jdk11](https://github.com/scala/bug/labels/jdk11), [jdk17](https://github.com/scala/bug/labels/jdk17), [jdk21](https://github.com/scala/bug/labels/jdk21), and [jdk25](https://github.com/scala/bug/labels/jdk25) labels in [the Scala 2 bug tracker](https://github.com/scala/bug/issues).
@@ -147,10 +168,3 @@ A few sbt plugins are offering support for GraalVM Native Image compilation:
147168

148169
- [sbt-native-packager](https://www.scala-sbt.org/sbt-native-packager/formats/graalvm-native-image.html)
149170
- [sbt-native-image](https://github.com/scalameta/sbt-native-image)
150-
151-
## Scala 3
152-
153-
At present, both Scala 3.3 LTS and Scala Next support JDK 8, as well as 11 and beyond.
154-
155-
As per [this blog post](https://www.scala-lang.org/news/next-scala-lts-jdk.html),
156-
Scala 3.8 will have a new minimum JDK version of 17. This can already be tested in Scala 3.8 nightlies.

0 commit comments

Comments
 (0)