feat!: API 34 Support

[breautek]

Platforms affected

Android

Motivation and Context

Adds in support for the next android platform

Closes #1661
Closes #1596

Description

This PR supercedes and includes #1596

This PR does a few different things to provide API 34 support which will be noted below.

Breaking Changes

These are notable changes that is breaking that may affect plugins or workflows. It doesn't highlight all breaking changes in which were hidden inside implementation details.

• JDK 17 is now required
• Cordova-Android will now use Gradle 8.7 by default
• Android Studio Jellyfish. Android Studio is not required for building via the Cordova CLI.

Default Configuration Changes

Target SDK: 34
Gradle Version: 8.7
AGP Version: 8.3.0
Kotlin JVM Target: 1.8 (If kotlin is enabled)
Min Build Tools: 34

Java/Kotlin Changes

Source/Target compatibility we changed from Java 8 to 17 on both the framework and app template projects.

Source & Target compatibility have been reverted back to 8, but 2 new preferences are added to allow developers to experiment: AndroidJavaSourceCompatibility and AndroidJavaTargetCompatibility which adjusts the respective gradle compile options. By default, these values are 8, which is the same values used before.

Additionally, AndroidKotlinJVMTarget preference was added to select the Kotlin JVM target. By default, the Kotlin JVM Target will be same as AndroidJavaTargetCompatibility. Updating AndroidJavaTargetCompatibility will influence the Kotlin JVM target unless if AndroidKotlinJVMTarget is also explicitly defined.

BuildConfig

Previously this I believe was implicitly enabled, but now needs to be explictly enabled otherwise the following may occur

* What went wrong:
A problem occurred configuring project ':app'.
> com.android.builder.errors.EvalIssueException: defaultConfig contains custom BuildConfig fields, but the feature is disabled.
  To enable the feature, add the following to your module-level build.gradle:
  `android.buildFeatures.buildConfig true`

I however did not encounter this on a simple project, so it might be required depending on what the plugins does.

AGP 8.3

AGP 8.2 is the minimum version required for API 34 builds. Attempting build against API 34 on earlier versions will produce warnings and/or errors.

AGP 8.3 is however the latest version that can be used with standard Android Studio configurations.

AGP 8.4 was tested with and will mostly work, but will not work inside Android Studio without further configuration. Because we don't want to impose Android Studio configurations onto the user, AGP 8.3 is chosen for cordova-android@13 release.

Gradle -b flag

This flag has been deprecated and scheduled to be removed in gradle's next major release.
The gradle projects must follow a standard structure now. Cordova's generated project already follows the standard structure thus for cordova build commands the -b append can simply just be removed, we don't need to explicitly declare the build.gradle file.

It was also used against the wrapper.gradle file which changes are noted below.

gradle.wrapper

The "intentionally empty" gradle.wrapper file has been removed.

We no longer manually manage gradle versions. Instead, we let gradle do it for us by utilising their --gradle-version argument. A new function was introduced to replace the old runGradleWrapper to:

1. setup the gradle wrapper if not already present
2. install/update the gradle wrapper to the specified version.

By default, this will be 8.7 as defined in the defaults json config file, but may be overwritten by GradleVersion preference, or CORDOVA_ANDROID_GRADLE_DISTRIBUTION_URL environment variable.

If CORDOVA_ANDROID_GRADLE_DISTRIBUTION_URL is defined, the preference will be ignored and --distribution-url will be used instead, maintaining the ability for corporations to install their own gradle wrapper from their own source.

The Gradle Wrapper was previously checked into the repo and was removed. It has since returned as using the system gradle to generate the wrapper caused issues. Namely it would require end-users to have an appropriate gradle version that satisfies AGP, which kind of defeats the purpose of using wrappers.

Because -b flag will be going away, there is now a tools project that is templated and copies. This project serves as the old wrapper.gradle, in that it's an empty project that can be used by the system gradle of a varying version range to produce the gradle wrapper at the version that we need to build the android project.

~obsolete gradle-wrapper notes~

This section is no longer in the PR

While personally I do not agree with how Gradle handles this, it is their recommendation to check in the Gradle wrapper, including the jar file into the source.

To make the Wrapper files available to other developers and execution environments, you need to check them into version control. Wrapper files, including the JAR file, are small. Adding the JAR file to version control is expected. Some organizations do not allow projects to submit binary files to version control, and there is no workaround available.

As usual, you should commit the changes to the Wrapper files to version control.

This done for both our test project and the app template. On platform add, the wrapper will be copied from the template. Individual projects via GradleVersion may change the wrapper version.

Should the end user choose a gradle version below what was required by AGP, gradle will update the gradle version, but builds will fail. Attempting to update the version back to an acceptable version will cause the gradle wrapper task to fail as the wrapper task also loads in AGP. To avoid this, Cordova does a version check before executing the wrapper task and will not update the wrapper if it's below the minimum required.

Note that while by preference both Gradle Version and AGP versions are configurable, the version check is not. This means that even if you drop Gradle and AGP down a version, the current >= 8.6 check will remain. I think this is OK since these preferences are documented for internal development use.

Lastly, because of the introduction of using --gradle-version and letting gradle manage our wrappers, the clean gradle wrapper script we had for our test project became obsolete and was removed.

Android Studio

With AGP 8.3, Android Studio Jellyfish will now be required for opening the native project.

CI

JDK was updated from 11 to 17, which is a requirement to build for API 34

Testing

Ran NPM test
Ran in sample cordova hello world app, with variety of different configurations
Ran in one of my projects

Known Issues

• The core splashscreen plugin does not compile when targeting JDK 17.

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 86.36364% with 3 lines in your changes are missing coverage. Please review.

Project coverage is 72.50%. Comparing base (ed8e5d2) to head (b974bba).

Files	Patch %	Lines
lib/builders/ProjectBuilder.js	80.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1678      +/-   ##
==========================================
+ Coverage   72.15%   72.50%   +0.35%     
==========================================
  Files          23       23              
  Lines        1839     1837       -2     
==========================================
+ Hits         1327     1332       +5     
+ Misses        512      505       -7     

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

[breautek]

I consider it a 'hard requirement' for users to upgrade to Android Studio Jellyfish at a minimum for successful builds and seamless functionality from Android Studio, as the term 'recommended' suggests that the version is not mandatory.

Older versions of Android Studio are not compatible with AGP 8.4 and will fail.

I've updated the wording, also added a smaller Breaking Changes section that highlights in short bullet-form of the notable breaking changes.

[breautek]

I've reverted AGP down to 8.3

Jellyfish appears to bundle Gradle 8.4 by default and will fail on installing the wrapper due to AGP 8.4's requirement on Gradle 8.6. In order to use AGP 8.4 on Jellyfish, the user would have to do additional configurations to specify an alternate gradle.

[github-advanced-security]

This pull request sets up GitHub code scanning for this repository. Once the scans have completed and the checks have passed, the analysis results for this pull request branch will appear on this overview. Once you merge this pull request, the 'Security' tab will show more code scanning analysis results (for example, for the default branch). Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results. For more information about GitHub code scanning, check out the documentation.

[erisu]

Code LGTM

I have tested the following:

• cordova platform add
• cordova build android
• Android Studio Jellyfish
  • Gradle Sync
  • Build and Run on Emulator

I confirmed that Gradle 8.7 and AGP 8.3 is used.

[ramona-cristea]

Hello,

Does Cordova support Android 14? I saw you were working on it (api34-support), but didn't see any update on the oficial documentation here https://cordova.apache.org/docs/en/12.x/guide/platforms/android/index.html ?
Is there a version 13.0.0 of Cordova which targets Android 14? Thank you!

[breautek]

Is there a version 13.0.0 of Cordova which targets Android 14? Thank you!

Yes. See here for more details.