fix: configure gradle java.home

[erisu]

Motivation, Context & Description

Fix an issue mentioned in a discussion thread.

1. Ensure that Cordova-Android properly creates config.properties.
2. Ensure that java.home is set correctly:
   1. Check and use the CORDOVA_JAVA_HOME environment variable.
   2. If CORDOVA_JAVA_HOME is missing, fall back to JAVA_HOME.
   3. If neither is set, remove the java.home property (if previously set), allowing Android Studio to display a warning and configure its internal Java automatically.
3. Copy the tools/.gradle directory up one level.

Note: Step 2.3 should not occur under normal conditions, but was included as a safeguard. When running cordova build, if JAVA_HOME is missing, its expected to not continue as its apart of the requirement checks.

This change also ensures that Cordova-Android uses the correct Java version specified by the user via environment variables. According to the Cordova documentation, these variables must be configured for Cordova-Android setup. Defaulting to Android Studio's bundled Java could lead to unexpected results and not using versions that the App developer configured.

Additional Feedback

It appears that the change came from AGP 8.2. It created a new way to specify the JDK path was added and became default. This new macro is called GRADLE_LOCAL_JAVA_HOME

From Android Developer - Java versions in Android builds:

The macros enable dynamic project JDK path selection:

• JAVA_HOME: uses the environment variable with the same name
• GRADLE_LOCAL_JAVA_HOME: uses the java.home property in the .gradle/config.properties file which defaults to the JetBrains Runtime.

Testing

• Create project
• Add cordova-android platform with changes
• Build for Android

1. Use Case 1.a

Confirmed that java.home was set with configured environment variables.

2. Use Case 1.b

Re-run build with CORDOVA_JAVA_HOME set to another version of Java and confirmed the java.home was updated.

3. Use Case 2

Created a before_build hookscript which would run before cordova build.
Confirm that the additional properties, defined in the hookscript, were injected in the config.properties file and that java.home was set correctly by the build script.

Checklist

• I've run the tests to see all new and existing tests pass
• I added automated test coverage as appropriate for this change
• Commit is prefixed with (platform) if this change only applies to one platform (e.g. (android))
• If this Pull Request resolves an issue, I linked to the issue in the text above (and used the correct keyword to close issues using keywords)
• I've updated the documentation if necessary

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 0% with 12 lines in your changes missing coverage. Please review.

Project coverage is 72.11%. Comparing base (f697ca7) to head (501467d).

Files with missing lines	Patch %	Lines
lib/builders/ProjectBuilder.js	0.00%	12 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1795      +/-   ##
==========================================
- Coverage   72.58%   72.11%   -0.48%     
==========================================
  Files          23       23              
  Lines        1835     1847      +12     
==========================================
  Hits         1332     1332              
- Misses        503      515      +12     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dpogue]

LGTM

[GitToTheHub]

Hi,

JAVA_HOME not applied in config.properties

I did set JAVA_HOME:

/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

(macOS)

.gradle/config.properties has the content:

#Sun Mar 30 17:59:48 CEST 2025
java.home=/Applications/Android Studio.app/Contents/jbr/Contents/Home

Points to something in the Android Studio app

Is this normal?

Build without JAVA_HOME or CORDOVA_JAVA_HOME

You wrote:

When running cordova build, if JAVA_HOME is missing, its expected to not continue as its apart of the requirement checks.

When I didn't set anything I can build successfully. The java command is still available, maybe it's working because of this.

[erisu]

Can you provide the exact step you used to get that result?

I don't get Android Studio's jbr with this PR.

% echo $JAVA_HOME
/Users/cordova/.sdkman/candidates/java/current

% cordova create cordovaTest com.erisu.cordovaTest cordovaTest
% cd cordovaTest
% cordova platform add github:erisu/cordova-android\#feat/set-gradle-java-home
% cordova build android

% cat platforms/android/.gradle/config.properties
java.home=/Users/cordova/.sdkman/candidates/java/current

If you are not building with Cordova and only opening with Android Studio, you wont have the right value and there is nothing we can do about that.

[erisu]

Build without JAVA_HOME or CORDOVA_JAVA_HOME

You wrote:

When running cordova build, if JAVA_HOME is missing, its expected to not continue as its apart of the requirement checks.

When I didn't set anything I can build successfully. The java command is still available, maybe it's working because of this.

Here is example of what I mean by builds wont work when JAVA_HOME is missing.

% echo $JAVA_HOME
/Users/cordova/.sdkman/candidates/java/current

% unset JAVA_HOME
% echo $JAVA_HOME

% cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=/Users/erisu/Library/Android/sdk (recommended setting)
ANDROID_SDK_ROOT=/Users/erisu/Library/Android/sdk (DEPRECATED)
Failed to find 'JAVA_HOME' environment variable. Try setting it manually.

Build failed the requirement check and stopped.

[GitToTheHub]

Hi,

after adding the platform via

cordova platform add github:erisu/cordova-android\#feat/set-gradle-java-home

I opend it with Android Studio and get the result I described. I didn't build anything in Android Studio, just opened it.

Edit:

When I do cordova build android after adding the platform without opening the project in Android Studio the path is correct.
But opening it in Android Studio should be supported, or?

[GitToTheHub]

Build without JAVA_HOME or CORDOVA_JAVA_HOME

You wrote:

When running cordova build, if JAVA_HOME is missing, its expected to not continue as its apart of the requirement checks.

When I didn't set anything I can build successfully. The java command is still available, maybe it's working because of this.

Here is example of what I mean by builds wont work when JAVA_HOME is missing.

% echo $JAVA_HOME
/Users/cordova/.sdkman/candidates/java/current

% unset JAVA_HOME
% echo $JAVA_HOME

% cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=/Users/erisu/Library/Android/sdk (recommended setting)
ANDROID_SDK_ROOT=/Users/erisu/Library/Android/sdk (DEPRECATED)
Failed to find 'JAVA_HOME' environment variable. Try setting it manually.

Build failed the requirement check and stopped.

I did it like you wrote, but the build succeded:

% echo $JAVA_HOME
/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
% unset JAVA_HOME
% echo $JAVA_HOME

% cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=/Users/manuelbeck/Library/Android/sdk (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)
Using Android SDK: /Users/manuelbeck/Library/Android/sdk
Reading build config file: /Users/manuelbeck/Projekte/app_entwicklung/abfuhr_app/build.json
Reading the keystore from: /Users/manuelbeck/Projekte/app_entwicklung/abfuhr_app/Signierung/Android/netactive.keystore

BUILD SUCCESSFUL in 261ms

[erisu]

I opend it with Android Studio and get the result I described. I didn't build anything in Android Studio, just opened it.

If you opened with Android Studio and you did not run cordova build first, then yes you will get Android Studio's JBR and is expected behavior.

[GitToTheHub]

If you opened with Android Studio and you did not run cordova build first, then yes you will get Android Studio's JBR and is expected behavior.

So I have to always first do cordova build android before opening it the first time in Android Studio? If yes, this should be documented.

[erisu]

This PR only focuses on resolving the issue with cordova build. Running cordova build should properly detect JAVA_HOME and update the gradle config.

However, this PR does not address cases if users open Android Studio first. In that scenario, it's expected that you'll see a warning on the first load, and then Android Studio configures the java.home with JBR.

Ideally, running cordova build first shouldn’t be a requirement—users should be able to just open Android Studio. But unfortunately, fixing the issue where JBR is configured on first launch is not something that might be resolved until next major release.

Currently, Cordova doesn’t create the Gradle wrapper until the project is built using the Cordova command. As far as I remember, it has always worked this way.

To support opening a project in Android Studio immediately after adding the platform, Cordova would need to move the Gradle wrapper build process earlier in the workflow—perhaps at the end of platform add, or even during prepare, since that runs after adding a platform. If on prepare, it would also trigger on every plugin add, unfortunately.

Hook scripts already allow users to run custom scripts during key phases, like after_platform_add and before_compile. If we could also execute the Gradle wrapper build at these points, that would be ideal—but again, this would require major changes.

[GitToTheHub]

Hi,

thanks for the explanation. I unterstand that this is not in scope of this pr. I only mentioned it because I noticed it.
But it sounds like you already have some ideas :) Maybe a build could be triggered after platform add? So the user sees already if everything is ok with it.