Add Apple Silicon build workaround

[chrisrueger]

Add a local-only hack / workaround for building on MacOS Apple Silicon when you don't have a JDK9 and/or JDK16 on your system.

Problem was:

On my Macbook M3 I had trouble building freemarker.

./gradlew jar                                                   

FAILURE: Build failed with an exception.

* What went wrong:
Could not determine the dependencies of task ':jar'.
> Could not resolve all dependencies for configuration ':combinedClasspath'.
   > Failed to calculate the value of task ':compileCore9Java' property 'javaCompiler'.
      > No matching toolchains found for requested specification: {languageVersion=9, vendor=any, implementation=vendor-specific} for MAC_OS on aarch64.
         > No locally installed toolchains match and the configured toolchain download repositories aren't able to provide a match either.

* Try:
> Learn more about toolchain auto-detection at https://docs.gradle.org/8.5/userguide/toolchains.html#sec:auto_detection.
> Learn more about toolchain repositories at https://docs.gradle.org/8.5/userguide/toolchains.html#sub:download_repositories.
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

BUILD FAILED in 9s
5 actionable tasks: 1 executed, 4 up-to-date

Can't remember exactly but AIs of this world recommended Azul somehow.
I managed to get an old Azul JDK 1.8 and 16, but could not find a Azul JDK 9 (https://www.azul.com/downloads/?package=jdk#zulu) .
So I started commenting out some sections in build.gradle.kts.

In this PR

./gradlew -Pfreemarker.javaVersionUsedFor.9=11 -Pfreemarker.javaVersionUsedFor.16=17 jar

This basically says the build should use JDK11 instead of JDK9 and JDK17 instead of JDK16.

Use this to avoid MR-JAR toolchain errors when JDK9/16 are unavailable.

[ddekany]

But then the resulting jar won't support the Java 9 and 16 features (will miss META-INF\versions\${javaVersion}).

What if instead you add an option to use Java 11 instead of 9, and Java 17 instead of 16? Maybe those Java version are available for Mac. In principle all you have to do is replacing the 2nd argument to configureSourceSet(sourceSetName, sourceSetJavaVersion). And also have to override the freemarker.javadoc.javaVersion and freemarker.test.javaVersion in gradle.properties then.

[chrisrueger]

Like this 12418b5 ? @ddekany

For debugging I added the following temporary task to build.gradle.kts :

tasks.withType<JavaCompile>().configureEach {
    doFirst {
        val md = javaCompiler.get().metadata
        logger.lifecycle(
            "TOOLCHAIN ${path}: lang=${md.languageVersion.asInt()} " +
                "vendor=${md.vendor} runtime=${md.javaRuntimeVersion} " +
                "home=${md.installationPath.asFile}"
        )
    }
}

which prints

> Task :compileCore9Java
TOOLCHAIN :compileCore9Java: lang=11 vendor=Eclipse Temurin runtime=11.0.31+11 home=/Users/christophrueger/.gradle/jdks/eclipse_adoptium-11-aarch64-os_x/jdk-11.0.31+11/Contents/Home

> Task :compileCore16Java
TOOLCHAIN :compileCore16Java: lang=17 vendor=Eclipse Temurin runtime=17.0.11+9 home=/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home

Gradle Toolchains look like this:

./gradlew -q javaToolchains

 + Options
     | Auto-detection:     Enabled
     | Auto-download:      Enabled

 + Azul Zulu JDK 1.8.0_452-b09
     | Location:           /Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home
     | Language Version:   8
     | Vendor:             Azul Zulu
     | Architecture:       aarch64
     | Is JDK:             true
     | Detected by:        MacOS java_home

 + Azul Zulu JDK 16.0.2+7
     | Location:           /Users/christophrueger/.gradle/jdks/azul_systems__inc_-16-aarch64-os_x/zulu16.32.15-ca-jdk16.0.2-macosx_aarch64/zulu-16.jdk/Contents/Home
     | Language Version:   16
     | Vendor:             Azul Zulu
     | Architecture:       aarch64
     | Is JDK:             true
     | Detected by:        Auto-provisioned by Gradle

 + Eclipse Temurin JDK 11.0.31+11
     | Location:           /Users/christophrueger/.gradle/jdks/eclipse_adoptium-11-aarch64-os_x/jdk-11.0.31+11/Contents/Home
     | Language Version:   11
     | Vendor:             Eclipse Temurin
     | Architecture:       aarch64
     | Is JDK:             true
     | Detected by:        Auto-provisioned by Gradle

 + Eclipse Temurin JDK 17.0.11+9
     | Location:           /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home
     | Language Version:   17
     | Vendor:             Eclipse Temurin
     | Architecture:       aarch64
     | Is JDK:             true
     | Detected by:        MacOS java_home

 + Eclipse Temurin JDK 21.0.3+9-LTS
     | Location:           /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home
     | Language Version:   21
     | Vendor:             Eclipse Temurin
     | Architecture:       aarch64
     | Is JDK:             true
     | Detected by:        Current JVM

 + Eclipse Temurin JDK 25.0.1+8-LTS
     | Location:           /Library/Java/JavaVirtualMachines/temurin-25.jdk/Contents/Home
     | Language Version:   25
     | Vendor:             Eclipse Temurin
     | Architecture:       aarch64
     | Is JDK:             true
     | Detected by:        MacOS java_home

[ddekany]

Something like that, except, you have committed the Java version overrides needed on Mac into gradle.properties that we release to everybody. This is of course something that you have to overreide locally, for example by command-line parameters.

The ultimate solution is maybe having something like freemarker.javaVersionUsedFor.9, and freemarker.javaVersionUsedFor.16, which is by default not set. Therefore you can set it in ~/gradle.properties, and you don't have to modify (and accidentally commit) the gradle.properties inside the project. But then where these properties are currently read we have use some method like javaVersionUsedFor(16), that handless the lookup and fallback logic. Another positive that this is the automatically works for the test and javadoc selection as well, as you mapped the Java version itself to the actual Java version to use. Just an idea anyway.

[chrisrueger]

@ddekany thanks for the feedback and sorry for the long delay.

I added your suggestions.

./gradlew -Pfreemarker.javaVersionUsedFor.9=11 -Pfreemarker.javaVersionUsedFor.16=17 jar

Can override this locally.

Some diagnostics you get by appending --info to verify the JDK overrides have an effect:

./gradlew -Pfreemarker.javaVersionUsedFor.9=11 -Pfreemarker.javaVersionUsedFor.16=17 jar --info

which prints:

TOOLCHAIN :compileCore16Java: lang=17 vendor=Eclipse Temurin runtime=17.0.11+9 home=/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home

[ddekany]

Merged with followup commit (only adjusts the README).