This is an automated email from the ASF dual-hosted git repository. vlsi pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/calcite.git
commit fe1c46d2beff6e1edcc050ffbb03df1724adbaf3 Author: Vladimir Sitnikov <[email protected]> AuthorDate: Fri Sep 25 11:14:07 2026 +0300 [CALCITE-4553] Document the JDK that compiles Calcite The build compiles with the jdkBuildVersion toolchain (JDK 25 by default) and --release 8, but howto.md listed only the JDKs that run Gradle, and develop/index.md still asked for JDK 8u220 because of javac 8 bugs with type annotations. Neither page said that Gradle on Java 8 cannot download the build JDK, and the Error Prone and Checker Framework commands failed on JDK 25 as written. Add a howto.md section on the build JDK with the error Gradle prints when it is missing, point the build prerequisites and the release steps to it, and pass -PjdkBuildVersion=11 in the Error Prone and Checker Framework commands. Drop the JDK 8u202 and CALCITE-6616 notes: both were about javac 8 or 21 compiling the code. Co-Authored-By: Claude Opus 5.5 <[email protected]> --- site/_docs/howto.md | 42 ++++++++++++++++++++++++++++++++++++++---- site/develop/index.md | 16 +++++++--------- 2 files changed, 45 insertions(+), 13 deletions(-) diff --git a/site/_docs/howto.md b/site/_docs/howto.md index 8be84ea2dd..1592e34006 100644 --- a/site/_docs/howto.md +++ b/site/_docs/howto.md @@ -33,6 +33,8 @@ ## Building from a source distribution Prerequisite is Java (JDK 8, 11, 17, 21 or 24) and Gradle (version 8.14.4) on your path. +The build compiles the code with JDK 25; +see [the JDK that compiles Calcite](#the-jdk-that-compiles-calcite). Unpack the source distribution `.tar.gz` file, `cd` to the root directory of the unpacked source, @@ -52,6 +54,8 @@ ## Building from Git Prerequisites are git and Java (JDK 8, 11, 17, 21 or 24) on your path. +The build compiles the code with JDK 25; +see [the JDK that compiles Calcite](#the-jdk-that-compiles-calcite). Create a local copy of the GitHub repository, `cd` to its root directory, @@ -76,6 +80,35 @@ ## Building from Git [Running tests](#running-tests) describes how to run more or fewer tests. +## The JDK that compiles Calcite + +Gradle compiles Calcite with JDK 25 (the `jdkBuildVersion` property selects it) +and passes `--release 8` to `javac`, +so the classes run on Java 8 and use only the Java 8 API. +Tests, javadoc, and other tasks that run Java use the JDK that runs Gradle, +so `JAVA_HOME` selects the JDK the tests run on. + +Gradle finds JDK 25 when it is installed in a standard location, +or in a directory listed in `org.gradle.java.installations.paths` +(see [toolchain auto-detection](https://docs.gradle.org/8.14.4/userguide/toolchains.html#sec:auto_detection)). +Otherwise, Gradle downloads it. +The download works only when Gradle runs on Java 11 or later, +so if you run Gradle on Java 8, install JDK 25 yourself. +Without it, compilation fails with: + +{% highlight text %} +Cannot find a Java installation on your machine (...) matching: {languageVersion=25, vendor=any vendor, implementation=vendor-specific, nativeImageCapable=false}. Some toolchain resolvers had internal failures: foojay (Requesting vendor list failed: error code: 1010 +{% endhighlight %} + +* `-PjdkBuildVersion=N` (integer, default `25`) selects the major version of + the JDK that compiles the code. + Error Prone 2.5.1 fails on JDK 25 with + `IllegalAccessError: class com.google.errorprone.JavacErrorDescriptionListener ... cannot access class com.sun.tools.javac.tree.JCTree$JCCompilationUnit`, + so run it and the Checker Framework with `-PjdkBuildVersion=11`, as CI does. +* `-Porg.gradle.java.installations.auto-download=false`, also accepted in + `gradle.properties`, makes the build fail instead of downloading a JDK. + The error then ends with `Toolchain auto-provisioning is not enabled.` + ## Gradle vs the Gradle Wrapper Calcite uses the Gradle Wrapper to make a consistent build environment. @@ -125,7 +158,7 @@ ## Running tests $ ./gradlew test # execute tests $ ./gradlew style # update code formatting (for auto-correctable cases) and verify style $ ./gradlew autostyleCheck checkstyleAll # report code style violations -$ ./gradlew -PenableErrorprone classes # verify Java code with Error Prone compiler, requires Java 11 +$ ./gradlew -PenableErrorprone -PjdkBuildVersion=11 classes # verify Java code with Error Prone compiler on JDK 11 {% endhighlight %} You can use `./gradlew assemble` to build the artifacts and skip all tests and verifications. @@ -705,7 +738,8 @@ ## Making a snapshot Before you start: -* Make sure you are using JDK 8. Note: you need Java 8u202 or later in case you use OpenJDK-based Java. +* Make sure you are using JDK 8, and that JDK 25 is installed + (see [the JDK that compiles Calcite](#the-jdk-that-compiles-calcite)). * Make sure build and tests succeed with `-Dcalcite.test.db=hsqldb` (the default) {% highlight bash %} @@ -733,8 +767,8 @@ ## Making a release candidate Report to [[email protected]](mailto:[email protected]) if new critical vulnerabilities are found among dependencies. The task requires a JDK 11 or later so it doesn't appear when using older versions. -* Make sure you are using JDK 8 for all subsequent steps. (Compiling with JDK 21 causes - [[CALCITE-6616](https://issues.apache.org/jira/browse/CALCITE-6616)].) +* Make sure you are using JDK 8 for all subsequent steps, and that JDK 25 is installed + (see [the JDK that compiles Calcite](#the-jdk-that-compiles-calcite)). * Check that `README` and `site/_docs/howto.md` have the correct version number. * Check that `site/_docs/howto.md` has the correct Gradle version. * Check that `NOTICE` has the current copyright year. diff --git a/site/develop/index.md b/site/develop/index.md index de3221609a..b0fc04b75b 100644 --- a/site/develop/index.md +++ b/site/develop/index.md @@ -41,14 +41,9 @@ ## Source code ## Download source, build, and run tests Prerequisites are Git, -and Java (JDK 8u220 or later, 11 preferred) on your path. - -Note: early OpenJDK 1.8 versions (e.g. versions before 1.8u202) are known to have issues with -producing bytecode for type annotations (see [JDK-8187805](https://bugs.openjdk.java.net/browse/JDK-8187805), -[JDK-8187805](https://bugs.openjdk.java.net/browse/JDK-8187805), -[JDK-8210273](https://bugs.openjdk.java.net/browse/JDK-8210273), -[JDK-8160928](https://bugs.openjdk.java.net/browse/JDK-8160928), -[JDK-8144185](https://bugs.openjdk.java.net/browse/JDK-8144185) ), so make sure you use up to date Java. +and Java (JDK 8, 11, 17, 21 or 24) on your path. +The build compiles the code with JDK 25; see +[the JDK that compiles Calcite]({{ site.baseurl }}/docs/howto.html#the-jdk-that-compiles-calcite). Create a local copy of the Git repository, `cd` to its root directory, then build using Gradle: @@ -236,7 +231,10 @@ ## Null safety To execute the Checker Framework locally please use the following command: - ./gradlew -PenableCheckerframework :linq4j:classes :core:classes + ./gradlew -PjdkBuildVersion=11 -PenableCheckerframework :linq4j:classes :core:classes + +`-PjdkBuildVersion=11` compiles with JDK 11, as CI does; see +[the JDK that compiles Calcite]({{ site.baseurl }}/docs/howto.html#the-jdk-that-compiles-calcite). Here's a small introduction to null-safe programming:
