(freemarker) branch 2.3-gae updated: README.md: Compressed/crossreferenced exotic JDK troubleshooting

[dd...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

asf-gitbox-commits pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git


The following commit(s) were added to refs/heads/2.3-gae by this push:
     new 3e0d0c02 README.md: Compressed/crossreferenced exotic JDK troubleshooting
3e0d0c02 is described below

commit 3e0d0c02f72c429f3c101fe46891df14a9b0539d
Author: ddekany <dd...@apache.org>
AuthorDate: Sun Aug 23 21:18:48 2026 +0200

    README.md: Compressed/crossreferenced exotic JDK troubleshooting
---
 README.md | 33 ++++++++++-----------------------
 1 file changed, 10 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index fae272cc..0d3dcc56 100644
--- a/README.md
+++ b/README.md
@@ -110,7 +110,8 @@ https://freemarker.apache.org/sourcecode.html
 You need JDK 8, JDK 16, and JDK 17 (only for some tests) to be installed
 (and [visible to Gradle](https://docs.gradle.org/current/userguide/toolchains.html)).
 That's because different parts of the source code target different Java versions,
-and Gradle requires the exact JDK version (not higher) for each.
+and Gradle requires the exact JDK version (not higher) for each. (If you have trouble
+getting these specific JDK versions, see troubleshooting below!)
 
 Be sure that your default Java version (which Gradle should use automatically) is at
 least 17!
@@ -142,6 +143,13 @@ FreeMarker needs to be loaded from `freemarker.jar` that contains the `META-INF/
 Multi-Release JAR Files). If you run a test, Gradle ensures that you have an up-to-date `freemarker.jar`, and
 that it's in the classpath. Without that, FreeMarker will behave as if you are on a lower Java version.
 
+### Troubleshooting "No matching toolchains found"
+
+Especially on MacOS / Apple Silicon / AArch64 you may have hard time finding the exact JDK version needed (like JDK 
+9 or 16), and the build will fail with `No matching toolchains found for requested specification`. But if you are not
+building for a public release, you may override those Java versions with something more commonly available, by adding
+something like `-Pfreemarker.javaVersionUsedFor.9=11 -Pfreemarker.javaVersionUsedFor.16=17` to your Gradle calls. (You 
+can also add `--info` to get diagnostic output about the toolchains actually used.)
 
 ### Maven-related build tasks
 
@@ -194,7 +202,7 @@ Originally done on IntelliJ IDEA Community 2023.3.2:
     prefixes (to select columns of text, hold Alt while selecting with the mouse.) Then
     go back to "Copyright" in the tree, and set "Default project copyright" to "ASL2".
 
-### Eclipse
+### Eclipse (maybe outdated)
 
 This section wasn't updated long ago. But you should import the project as any other
 Gradle project. After that, it's recommended to set these preferences (based on Eclipse Mars):
@@ -251,24 +259,3 @@ Gradle project. After that, it's recommended to set these preferences (based on
   - Project -> Properties -> FindBugs -> [x] Run Automatically
   - There should 0 errors. But sometimes the plugin fails to take the
     @SuppressFBWarnings annotations into account; then use Project -> Clean. 
-
-
-## Troubleshooting
-
-### Problems building on MacOS / Apple Silicon / aarch64
-
-If you run into build problems on MacOS (e.g. `No matching toolchains found for requested specification: {languageVersion=9, vendor=any, implementation=vendor-specific} for MAC_OS on aarch64.`) that means that you don't have JDK9 / JDK16 installed on your system. 
-
-You override the java versions used for JDK9 and JDK16:
-
-```
-./gradlew -Pfreemarker.javaVersionUsedFor.9=11 -Pfreemarker.javaVersionUsedFor.16=17 jar
-```
-
-This is helpful if you don't have a JDK9 / JDK16 for MacOS installed on your system and just want to build e.g. with another replacement locally during development.
-
-You can append `--info` to get diagnostic output like this:
-
-```
-TOOLCHAIN :compileCore16Java: lang=17 vendor=Eclipse Temurin runtime=17.0.11+9 home=/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home
-```