Skip to content

Require JDK 25 with an actionable pre-flight error; drop legacy 6.08 docs#7665

Open
Vest wants to merge 1 commit into
PCGen:masterfrom
Vest:require-jdk25-preflight
Open

Require JDK 25 with an actionable pre-flight error; drop legacy 6.08 docs#7665
Vest wants to merge 1 commit into
PCGen:masterfrom
Vest:require-jdk25-preflight

Conversation

@Vest

@Vest Vest commented Jul 5, 2026

Copy link
Copy Markdown
Contributor

Improves the newcomer / drive-by-contributor experience for the JDK 25 requirement introduced in #7611. Two orthogonal but paired changes.

Problem

A contributor testing PR #7660 on Windows 10 with an older JDK hit:

* Where: Build file '...\PCGen\build.gradle' line: 252
> Could not resolve all dependencies for configuration ':runtimeClasspath'.
   > Failed to calculate the value of task ':compileJava' property 'javaCompiler'.
      > Cannot find a Java installation on your machine (Windows 10 10.0 amd64)
        matching: {languageVersion=25, vendor=any vendor, implementation=vendor-specific,
        nativeImageCapable=false}. Toolchain download repositories have not been
        configured.

The error is accurate but opaque — it points at a build.gradle line unrelated to the actual problem, doesn't name what version is required, doesn't name what version the user has, and doesn't tell them where to get a matching JDK. Meanwhile the README still documents parallel 6.08 (JDK 11) and 6.09 (JDK 25) install paths, which is confusing for someone landing on master trying to figure out which one applies.

build.gradle — pre-flight toolchain check

Installs a gradle.taskGraph.whenReady hook that calls javaToolchains.launcherFor(java.toolchain).get() before any JavaCompile task runs. This uses the same resolution path compileJava itself would use, so it correctly accepts every legitimate setup:

  • JAVA_HOME pointing at JDK 25+
  • Standard OS install locations Gradle auto-discovers
  • -Porg.gradle.java.installations.paths=<path> (the friend's workaround)
  • Global ~/.gradle/gradle.properties org.gradle.java.installations.paths

On failure, replaces the opaque error with:

PCGen requires JDK 25 to build, but Gradle could not find one on this machine.

Currently running: Java 21.0.4
                   at C:\Program Files\Eclipse Adoptium\jdk-21.0.4.7-hotspot

Install JDK 25 (or newer) and either:
  - Set JAVA_HOME to it, or
  - Run: ./gradlew -Porg.gradle.java.installations.paths=<path-to-jdk-25> <task>

Verify Gradle can see it:  ./gradlew -q javaToolchains

Downloads:
  - Adoptium Temurin: https://adoptium.net/temurin/releases/?version=25
  - Azul Zulu:        https://www.azul.com/downloads/?version=java-25-lts
  - SapMachine:       https://sapmachine.io/

The check fires only when a task in the graph is a JavaCompile, so ./gradlew help, ./gradlew tasks, ./gradlew javaToolchains, and ./gradlew --version remain usable even without JDK 25 installed — a
newcomer can still run ./gradlew -q javaToolchains to discover what JDKs their machine has.

Required version is sourced from project.ext.javaVersion (i.e. gradle.properties), so future bumps stay one-line changes per the README's "Bumping Java / JavaFX versions" section.

Why not auto-download the JDK?

Auto-provisioning a JDK 25 (e.g. via the Foojay resolver plugin) would require adding a new plugin dependency, and installing the toolchain is not a build responsibility PCGen wants to take on — it's fine for it to be a prerequisite the contributor handles once. Recent commits have been moving in the opposite direction: af1640a877 Drop controlsfx dependency, e23ea79cb7 build.gradle: drop stale forceMerge entries, etc. This PR adds no dependency; it only improves the diagnostic when the prerequisite is missing.

README.md — drop 6.08

Current version is 6.09.08.RC1 and every recent tag is 6.09.x. The README documented 6.08 and 6.09 install paths in parallel:

  • TOC entry Installing From Release 6.08
  • Full install section recommending JDK 11
  • Second install section titled Installing From Release 6.09 (Alpha)
  • Two-line dev-Java section: "For 6.08 development you will want Java with a minimum version of 11. / For 6.09 development you will want Java with a minimum version of 25."

Removed:

  • 6.08 TOC entry (renumbered subsequent entries 2–7)
  • Entire 6.08 install block (12 lines)
  • 6.08 dev-Java line
  • "(Alpha)" qualifier on the remaining install section — master ships 6.09 as the product; the alpha framing is stale.

Kept:

  • The remaining install section, renamed Installing PCGen
  • The 6.09 dev-Java line, simplified to "For development you will want Java with a minimum version of 25."

Verified

Command Result
./gradlew help Build succeeds — no toolchain resolution triggered (positive path for non-compile tasks)
./gradlew compileJava --dry-run Build succeeds — toolchain resolved via javaToolchains.launcherFor(...) on machine with JDK 25 (positive path for compile tasks)

Not verified locally: the negative path (message renders when no JDK 25 present), because my machine has JDK 25. The logic is small and eyeballable, but if a reviewer wants end-to-end confidence, temporarily bumping javaVersion=99 in gradle.properties will trigger it.

Out of scope

  • Updating 6.09.xx-in-a-URL patterns in the remaining install instructions — that's a docs decision about tracking /releases/latest vs. explicit versioning, deserves its own PR.

@Vest Vest force-pushed the require-jdk25-preflight branch 3 times, most recently from cfe612e to 3a4101a Compare July 5, 2026 20:42
…docs

build.gradle: install a taskGraph.whenReady hook that resolves the
Java toolchain before any JavaCompile task runs. On failure, replace
Gradle's "Toolchain download repositories have not been configured"
message with the daemon's current version, its java.home, four vendor
download links, and the exact -Porg.gradle.java.installations.paths
invocation. Non-compile tasks (help, tasks, javaToolchains) are
unaffected, so newcomers can still introspect their setup.

README.md: master ships 6.09 — drop the parallel 6.08 install path
(JDK 11 recommendation, separate TOC entry, "6.09 (Alpha)" qualifier
on the remaining install section) and simplify the dev-Java line to
just name JDK 25.
@Vest Vest force-pushed the require-jdk25-preflight branch from 3a4101a to 3a33d5e Compare July 5, 2026 20:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant