Skip to content

Build the Android template on current and future JDKs - #552

Draft
simonhamp wants to merge 2 commits into
mainfrom
fix/modern-jdk
Draft

simonhamp wants to merge 2 commits into
mainfrom
fix/modern-jdk

Conversation

@simonhamp

@simonhamp simonhamp commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

Android builds fail straight away when Gradle runs on Java 25, which is the JDK Android Studio bundles now (2026.2 ships JBR 25.0.3). The whole error is:

* What went wrong:
25.0.3

The template's Gradle 8.14.5 compiles the .kts build scripts with an embedded Kotlin 2.0.21 compiler, and that compiler throws IllegalArgumentException: 25.0.3 when it parses the running JVM's version. AGP never even loads. Anyone whose JAVA_HOME or default JDK is newer than the template's Gradle supports gets this, and the next JDK would do it again.

Version moves

Before After
Gradle wrapper 8.14.5 9.8.2 (runs on JDK 17 to 27)
Android Gradle Plugin 8.13.2 9.4.0
Kotlin 2.0.0 2.4.21
Gradle daemon JDK whatever launched Gradle pinned to 25

compileSdk, the NDK, compileOptions (Java 17 bytecode) and every library version are unchanged.

Keeping it working on future JDKs

The template now has gradle/gradle-daemon-jvm.properties, which tells Gradle which JDK the daemon must run on. Gradle uses a matching JDK it finds locally, or downloads that one (Temurin, through the foojay URLs in the file) into ~/.gradle/jdks. JAVA_HOME then only has to start the Gradle launcher, which works on any JDK 17 or newer. A new JDK on a developer's machine can't reach the code that broke here, because the build itself always runs on 25.

I picked this over the alternatives because it's the one mechanism that covers every way the project gets built: native:run, native:package, ./gradlew by hand, Android Studio (which reads the same file, and since Panda uses it for new projects by default) and Bifrost. A version check in native:run alone would leave the others exposed, and Java toolchains for compiling don't help when the failure is Gradle's own script compiler.

Why 25: it's the current LTS and what Android Studio ships, so most people already have it and nothing is downloaded. It's also the longest-lived choice if a future AGP or Gradle raises its minimum above 17.

The foojay resolver plugin isn't in settings.gradle.kts. It's only needed to regenerate the URLs, so the file has a comment on how to do that. Nothing extra is resolved at build time.

native:run and native:package

New GradleJava picks the Java that starts Gradle, in this order: NATIVEPHP_GRADLE_PATH (an existing config key that nothing read until now), JAVA_HOME, Android Studio's bundled JDK, then java on the PATH. It skips anything older than 17.

  • With no JAVA_HOME, Gradle is started with Android Studio's JDK. Before this, the build failed on this Mac because there's no Java on the PATH.
  • Android Studio's JDK is passed as -Dorg.gradle.java.installations.paths, because Gradle doesn't find it on its own. That lets the pin match it instead of downloading.
  • If nothing usable is found, the build stops before any work with the reason ("JAVA_HOME points to Java 11...") and the fix.
  • If an app updates the package but still has an old nativephp/android (Gradle 8, no pin) and Java is 25 or newer, native:run now stops in a second with "This Android project uses Gradle 8.14.5, which can't run on Java 25 (JAVA_HOME)" and tells you to run native:install android.
  • native:debug reports this Java instead of whatever java -version says.

AGP 9 changes in the template

  • Kotlin is built into AGP 9, so org.jetbrains.kotlin.android is gone, and kotlinOptions becomes a top-level kotlin { compilerOptions {} }. jvmTarget now follows targetCompatibility.
  • Built-in Kotlin doesn't compile Kotlin files added through java.srcDir, so the plugin compiler's src/nativephp/kotlin root is registered with kotlin.directories. registerPluginSourceRoot() still injects java.srcDir for scaffolds that predate the root, which are all AGP 8.
  • AGP 9 made R8 stricter: -keep class X no longer keeps X's no-arg constructor. android.r8.strictFullModeForKeepRules=false keeps the old meaning for plugin and custom_proguard_rules keep rules. The template and its first-party plugins also ran fine with strict mode on, so this can go once plugin rules are checked.
  • I didn't opt out of AGP 9's optimized resource shrinking. The opt-out is already deprecated and AGP 10 removes it. It only applies when an app turns on shrink_resources, but those apps should check that resources looked up by name (the splash drawable, plugin sounds) survive.

What an app has to do

Run php artisan native:install android again. It replaces nativephp/android with the new template, so anything edited by hand in there is lost, as usual.

Plugin authors: the kotlin-kapt plugin doesn't work with built-in Kotlin (KSP does), and any Gradle plugin declared in android.gradle_plugins has to support AGP 9. None of the first-party plugins use kapt. I haven't checked com.google.gms.google-services 4.4.3 (the Firebase plugin) against AGP 9.

CI

A second commit adds .github/workflows/android-template.yml. The job makes a fresh Laravel app, installs this branch, and builds a minified release APK with native:run, which runs AGP, Kotlin, CMake, lint and R8:

  • launcher on JDK 17 and on the latest JDK, with the pin (the developer path, including the JDK download),
  • daemon on JDK 17, 21 and the latest JDK, with the pin removed, to show the toolchain itself still works on them and when the pin can move,
  • the newest Gradle release in place of the wrapper's.

"Latest" is looked up from Adoptium on each run. It runs weekly as well as on template changes, so a new JDK or Gradle release that breaks the template fails there first. It uses ubuntu-latest and installs SDK 36 with sdkmanager, so it doesn't have the SDK 34 problem that parked test-package.yml.

Verified

On an Android emulator (API 35, arm64), with a fresh native:install android of this branch into mobile-starter (mobile-ui and mobile-browser installed), each a clean build that installed and launched:

  • JAVA_HOME = Android Studio's JBR 25.0.3
  • JAVA_HOME = Temurin 21, daemon on the pinned 25
  • JAVA_HOME = Temurin 27, daemon on the pinned 25
  • no JAVA_HOME and no Java on the PATH (picked Android Studio's JDK)
  • pin removed, daemon on Temurin 17, 21 and 27
  • a minified profileable build (R8 ran, 7.9 MB of dex), with the keep-rule opt-out and with strict mode, rendering the starter screen
  • launcher on Homebrew JDK 23: Gradle downloaded Temurin 25.0.4.1 from the pinned URL and built. With downloads off it fails with "Cannot find a Java installation on your machine matching: {languageVersion=25...}"

The old template (Gradle 8.14.5) on JBR 25 reproduced the original error. The package's tests pass (vendor/bin/pest: 1584 passed), and the existing Tests, Static Analysis and Code Style checks pass on this PR.

Worth watching

  • The first build on a machine without JDK 25 downloads about 200 MB inside the Gradle process, which counts against native:run's 600 second Gradle timeout (Don't stop Gradle after 600 seconds #500 removes it).
  • Bifrost's Android builders will download JDK 25 on first use unless they already have it.
  • Unrelated, found while testing: updateBuildConfiguration() rewrites every isMinifyEnabled in build.gradle.kts, including the profileable build type's hard-coded true. So profileable builds aren't minified unless NATIVEPHP_ANDROID_MINIFY_ENABLED is on.

🤖 Generated with Claude Code

simonhamp and others added 2 commits October 20, 2026 14:06
The template's Gradle 8.14.5 can't run on Java 25, which is what Android
Studio now bundles. Its Kotlin DSL compiler fails to parse the version and
the only error is "What went wrong: 25.0.3".

Move the template to Gradle 9.8.2, AGP 9.4.0 and Kotlin 2.4.21, and pin the
JDK the Gradle daemon runs on (25) in gradle/gradle-daemon-jvm.properties.
Gradle uses a matching local JDK or downloads that one, so a newer
JAVA_HOME only has to start the launcher.

AGP 9 has Kotlin built in, so the kotlin-android plugin and kotlinOptions
go, and the generated plugin sources are registered as Kotlin sources.
R8's stricter keep rules are held at the AGP 8 meaning for plugin rules.

native:run and native:package now pick the Java to start Gradle with
(NATIVEPHP_GRADLE_PATH, JAVA_HOME, Android Studio's JDK, then PATH), pass
Android Studio's JDK to Gradle so the pin can match it, and stop early with
a clear message when nothing fits or an older project can't run on the
current Java.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Builds a fresh app's Android project with native:run on JDK 17, 21 and the
latest JDK release, with the daemon JDK pin and without it, plus one leg on
the newest Gradle release. Runs weekly and when the template or the Android
build code changes, so a new JDK or Gradle release that breaks the template
fails here first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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