docs: add Java 25+ build troubleshooting for Gradle cache issue

Makefile

@@ -1,28 +1,46 @@
-.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
 	./gradlew classes testUnitParallel --parallel shadowJar
 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

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:**
+
+<details>
+<summary><strong>"Unsupported class file major version 69" error (Java 25+)</strong></summary>
+
+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+.
+</details>
+
+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

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
+```

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 = "149932a22";
 
     /**
      * Git commit date of the build (ISO format: YYYY-MM-DD).