diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index 71fe9ada12..704fba3af4 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -42,6 +42,7 @@ They're sorted by release and listed in alphabetical order: * [`FontWeight` also controls the weight attribute of variable fonts][] * [Deprecate `TextField.canRequestFocus`][] * [Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors][] +* [Migrating Flutter Android app to Android Gradle Plugin 9.0.0][] * [Material 3 tokens update][] [Merged threads on Linux]: /release/breaking-changes/linux-merged-threads @@ -50,6 +51,7 @@ They're sorted by release and listed in alphabetical order: [`FontWeight` also controls the weight attribute of variable fonts]: /release/breaking-changes/font-weight-variation [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus [Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors]: /release/breaking-changes/separated-builder-find-child-index-callback +[Migrating Flutter Android app to Android Gradle Plugin 9.0.0]: /release/breaking-changes/migrate-to-agp-9 [Material 3 tokens update]: /release/breaking-changes/material-color-utilities diff --git a/src/content/release/breaking-changes/migrate-to-agp-9.md b/src/content/release/breaking-changes/migrate-to-agp-9.md new file mode 100644 index 0000000000..1671529cce --- /dev/null +++ b/src/content/release/breaking-changes/migrate-to-agp-9.md @@ -0,0 +1,153 @@ +--- +title: Migrating Flutter Android app to Android Gradle Plugin 9.0.0 +description: >- + How to migrate your Flutter app's Android Gradle files + to build apps with Android Gradle Plugin 9.0.0+. +--- + +## Summary + +To build a Flutter app for Android, the Android Gradle Plugin (AGP) +must be applied. As of AGP 9.0.0, +the following migrations are required to successfully apply AGP 9+. + +First, built-in Kotlin is the new default, meaning any apps +using the `kotlin-android` plugin will not build successfully. +You must migrate from `kotlin-android` to built-in Kotlin. + +Second, AGP 9+ will only use the new AGP DSL interfaces. +This means any old DSL types will not be properly read. +The Flutter team is working on migrating old DSL types +to use the new DSL. In the meantime, you can set a gradle property flag +to use the old DSL. + +In a future Flutter release, support will be added for applying AGP 9+. +For now, all projects must be migrated manually. + +To learn more about Android Gradle Plugin, +see the [Android Gradle Plugin docs][AGP block]. + +## Migrate + +These instructions assume you are updating from +an AGP version created before 9.0.0 to an AGP version 9.0.0+. +You should also use the minimum compatible dependency versions +listed in the [Android Gradle Plugin docs][AGP block]. + +### Update the Gradle file + +If your app doesn't apply +the `kotlin-android` plugin (also called Kotlin Gradle Plugin), +then skip to the next step. + +First, find the `kotlin-android` plugin, likely located +in the `plugins` block of the `/android/build.gradle` +or `/android/build.gradle.kts` file. +As an example, consider the `build.gradle.kts` file from +a Flutter app created before this change: + +**Before**: +```kotlin +plugins { + id("com.android.application") + id("kotlin-android") + // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins. + id("dev.flutter.flutter-gradle-plugin") +} + +android { + ... + kotlinOptions { + jvmTarget = JavaVersion.VERSION_17.toString() + } + ... +} +... +``` + +Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: + +```kotlin diff +plugins { + id("com.android.application") + -id("kotlin-android") + // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins. + id("dev.flutter.flutter-gradle-plugin") +} + +android { + ... + -kotlinOptions { + -jvmTarget = JavaVersion.VERSION_17.toString() + -} + ... +} +``` + +Replace the `kotlinOptions` block with the following: + +```kotlin diff ++kotlin { + +compilerOptions { + +jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + +} ++} +``` + +Here is how the file will likely end up: + +**After**: +```kotlin +plugins { + id("com.android.application") + // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins. + id("dev.flutter.flutter-gradle-plugin") +} + +android { + ... + kotlin { + compilerOptions { + jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 + } + } + ... +} +... +``` + +### Set the Gradle property flag + +Next, to use the old AGP DSL, set the gradle property flag +`android.newDsl` to `false` in +your app's `/android/gradle.properties` file. + +```properties diff +org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError +android.useAndroidX=true ++ android.newDsl=false +``` + +### Validate + +Execute `flutter run` to confirm that your app builds and +launches on a connected Android device or emulator. + +## Timeline + +In stable release: TBD + +## References + +Relevant issue: +[Issue #175688][]: Audit flutter for compatibility with the AGP 9.0.0 + +The Gradle build files in your app vary based on the Flutter version +used when your app was created. +Consider staying up-to-date with the latest version +of the build files by periodically running `flutter upgrade` +in your app's directory. + +[AGP block]: {{site.android-dev}}/build/releases/gradle-plugin + +[Issue #175688]: {{site.github}}/flutter/flutter/issues/175688