From 149932a2232348971fcc399eab91834a3df9ad9b Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Fri, 27 Mar 2026 19:33:00 +0100 Subject: [PATCH 1/2] docs: add Java 25+ build troubleshooting for Gradle cache issue (#392) Add documentation for users experiencing "Unsupported class file major version 69" error when building with Java 25. The issue occurs when an old Gradle 8.x cache conflicts with the project's Gradle 9.0 wrapper. Changes: - QUICKSTART.md: Add collapsible troubleshooting section with fix - installation.md: Add comprehensive Troubleshooting section including: - Java version compatibility table (Java 22-25+) - Step-by-step fix for clearing old Gradle cache - Additional common issues (JAVA_HOME, slow builds) - Update prerequisites to clarify Java 22-25+ support Fixes #392 Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- QUICKSTART.md | 30 ++++++++- docs/getting-started/installation.md | 64 ++++++++++++++++++- .../org/perlonjava/core/Configuration.java | 2 +- 3 files changed, 92 insertions(+), 4 deletions(-) diff --git a/QUICKSTART.md b/QUICKSTART.md index e5a1e96d9..2980a98af 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -42,7 +42,35 @@ make The `make` command compiles the project and runs the fast unit tests. The complete build with tests typically completes in ~30 seconds. -**Build troubleshooting:** See [Installation Guide](docs/getting-started/installation.md) +**Build troubleshooting:** + +
+"Unsupported class file major version 69" error (Java 25+) + +If you see this error: +``` +BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 69 +> Unsupported class file major version 69 +``` + +This means you have Java 25+ but an old cached Gradle version that doesn't support it. Fix by clearing the old Gradle cache: + +```bash +# Linux/macOS +rm -rf ~/.gradle/wrapper/dists/gradle-8.* + +# Windows (PowerShell) +Remove-Item -Recurse -Force "$env:USERPROFILE\.gradle\wrapper\dists\gradle-8.*" + +# Then rebuild +make clean +make +``` + +The project uses Gradle 9.0+ (configured in the wrapper) which supports Java 22-25+. +
+ +For more troubleshooting: See [Installation Guide](docs/getting-started/installation.md#troubleshooting) **Debian/Ubuntu users:** You can also build and install a `.deb` package: ```bash diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 978ca4179..53dd7911e 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -21,10 +21,11 @@ - [Common Tasks](#common-tasks) - [Available Options](#available-options) - [Important Notes](#important-notes) +10. [Troubleshooting](#troubleshooting) ## Prerequisites -- Java 22 or higher -- Maven or Gradle +- Java 22 or higher (Java 22, 23, 24, 25+ are all supported) +- Maven or Gradle (Gradle wrapper included - recommended) - Optional: JDBC drivers for database connectivity ## Build Options @@ -211,3 +212,62 @@ make # Rebuild to include driver ``` **→ See [Configure.pl Reference](../reference/configure.md) for complete documentation** + +## Troubleshooting + +### "Unsupported class file major version 69" (Java 25+) + +**Problem:** When building with Java 25 or later, you see: +``` +BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 69 +> Unsupported class file major version 69 +``` + +**Cause:** An old cached Gradle version (8.x) doesn't support Java 25. Java 25 uses class file version 69, which requires Gradle 9.0+. + +**Solution:** Clear the old Gradle cache and rebuild: + +```bash +# Linux/macOS +rm -rf ~/.gradle/wrapper/dists/gradle-8.* +make clean +make + +# Windows (PowerShell) +Remove-Item -Recurse -Force "$env:USERPROFILE\.gradle\wrapper\dists\gradle-8.*" +gradlew.bat clean +make +``` + +The project includes a Gradle wrapper configured for Gradle 9.0+, which supports Java 22 through Java 25+. + +### Java Version Compatibility + +| Java Version | Class File Version | Gradle Required | +|--------------|-------------------|-----------------| +| Java 22 | 66 | 8.8+ | +| Java 23 | 67 | 8.10+ | +| Java 24 | 68 | 8.12+ | +| Java 25 | 69 | 9.0+ | + +PerlOnJava uses **Gradle 9.0** (configured in `gradle/wrapper/gradle-wrapper.properties`) to support all these versions. + +### "JAVA_HOME is not set" + +Make sure you have a JDK installed and JAVA_HOME is set: + +```bash +# Linux/macOS (add to ~/.bashrc or ~/.zshrc) +export JAVA_HOME=/path/to/jdk + +# Windows (System Properties > Environment Variables) +set JAVA_HOME=C:\path\to\jdk +``` + +### Build Takes Too Long + +Use `make dev` instead of `make` for faster builds during development - it skips tests: + +```bash +make dev # Compiles only, no tests +``` diff --git a/src/main/java/org/perlonjava/core/Configuration.java b/src/main/java/org/perlonjava/core/Configuration.java index 343ee3590..666164605 100644 --- a/src/main/java/org/perlonjava/core/Configuration.java +++ b/src/main/java/org/perlonjava/core/Configuration.java @@ -33,7 +33,7 @@ public final class Configuration { * Automatically populated by Gradle/Maven during build. * DO NOT EDIT MANUALLY - this value is replaced at build time. */ - public static final String gitCommitId = "6514d90c2"; + public static final String gitCommitId = "e35d35436"; /** * Git commit date of the build (ISO format: YYYY-MM-DD). From 6a55c14f327286b8330b031aa06b71385f96e1c7 Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Fri, 27 Mar 2026 19:35:28 +0100 Subject: [PATCH 2/2] fix: auto-detect and fix Java/Gradle version incompatibility in Makefile Add check-java-gradle target that automatically detects when Java 25+ is used with an incompatible Gradle version (< 9.0) and fixes it by: 1. Clearing old Gradle 8.x caches from ~/.gradle/wrapper/dists/ 2. Updating the wrapper to Gradle 9.0 The check runs before build, dev, and ci targets, ensuring users with Java 25+ can build without manual intervention. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- Makefile | 28 +++++++++++++++---- .../org/perlonjava/core/Configuration.java | 2 +- 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 7e6c14a95..7683a2ecd 100644 --- a/Makefile +++ b/Makefile @@ -1,20 +1,38 @@ -.PHONY: all clean test test-unit test-interpreter test-exiftool test-all test-gradle test-gradle-unit test-gradle-all test-gradle-parallel test-maven-parallel build run wrapper dev ci sbom sbom-java sbom-perl sbom-clean check-links +.PHONY: all clean test test-unit test-interpreter test-exiftool test-all test-gradle test-gradle-unit test-gradle-all test-gradle-parallel test-maven-parallel build run wrapper check-java-gradle dev ci sbom sbom-java sbom-perl sbom-clean check-links all: build # CI build - optimized for CI/CD environments -ci: wrapper +ci: check-java-gradle ifeq ($(OS),Windows_NT) mvn clean test -B else ./gradlew build --no-daemon --stacktrace endif -wrapper: +# Check Java/Gradle compatibility and fix if needed +check-java-gradle: @test -f ./gradlew || gradle wrapper +ifeq ($(OS),Windows_NT) + @echo "Checking Java/Gradle compatibility..." +else + @JAVA_MAJOR=$$(java -version 2>&1 | head -1 | sed -E 's/.*version "([0-9]+).*/\1/'); \ + GRADLE_VER=$$(grep distributionUrl gradle/wrapper/gradle-wrapper.properties | sed -E 's/.*gradle-([0-9]+)\..*/\1/'); \ + if [ "$$JAVA_MAJOR" -ge 25 ] && [ "$$GRADLE_VER" -lt 9 ]; then \ + echo ""; \ + echo "WARNING: Java $$JAVA_MAJOR detected but Gradle wrapper is version $$GRADLE_VER.x"; \ + echo "Java 25+ requires Gradle 9.0+. Updating wrapper..."; \ + echo ""; \ + rm -rf ~/.gradle/wrapper/dists/gradle-$$GRADLE_VER.*; \ + ./gradlew wrapper --gradle-version=9.0 2>/dev/null || gradle wrapper --gradle-version=9.0; \ + echo "Gradle wrapper updated to 9.0"; \ + fi +endif + +wrapper: check-java-gradle # Standard build - incremental compilation with parallel tests (4 JVMs) -build: wrapper +build: check-java-gradle ifeq ($(OS),Windows_NT) gradlew.bat classes testUnitParallel --parallel shadowJar else @@ -22,7 +40,7 @@ else endif # Development build - forces recompilation (use during active development) -dev: wrapper +dev: check-java-gradle ifeq ($(OS),Windows_NT) gradlew.bat clean compileJava shadowJar installDist else diff --git a/src/main/java/org/perlonjava/core/Configuration.java b/src/main/java/org/perlonjava/core/Configuration.java index 666164605..0975a3b6c 100644 --- a/src/main/java/org/perlonjava/core/Configuration.java +++ b/src/main/java/org/perlonjava/core/Configuration.java @@ -33,7 +33,7 @@ public final class Configuration { * Automatically populated by Gradle/Maven during build. * DO NOT EDIT MANUALLY - this value is replaced at build time. */ - public static final String gitCommitId = "e35d35436"; + public static final String gitCommitId = "149932a22"; /** * Git commit date of the build (ISO format: YYYY-MM-DD).