diff --git a/sites/docs/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md b/sites/docs/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md index 96f1cac1b3..2c034dbf21 100644 --- a/sites/docs/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md +++ b/sites/docs/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers.md @@ -4,8 +4,6 @@ description: >- Migrate Flutter apps to use built-in Kotlin. --- -## Migrate - This guide outlines the migration steps specifically for app developers. These instructions assume you are updating from @@ -13,25 +11,36 @@ 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]. -### Verify flags in properties file +:::note +To update Flutter plugins to use built-in Kotlin, +follow the [migration guide for plugin authors][]. +::: + +[AGP block]: {{site.android-dev}}/build/releases/gradle-plugin +[migration guide for plugin authors]: /release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors + + + +## Verify flags in the Gradle properties file Flutter sets the default behavior to use the legacy Kotlin Gradle Plugin (KGP) -and the old AGP DSL types to support projects that have not yet migrated. +and the old AGP DSL types to support projects that haven't yet migrated. The Flutter migrator tool automatically adds `android.builtInKotlin=false` and `android.newDsl=false` to your `gradle.properties` file. If these flags are missing from your `gradle.properties` file, -the Flutter tool automatically adds them when you next build or run your app -using `flutter run` or `flutter build apk`. +the Flutter tool automatically adds them when you +next build or run your app using `flutter run` or `flutter build apk`. -Alternatively, building the project using Android Studio tooling also adds -these flags automatically. +Alternatively, building the project using Android Studio tooling also +adds these flags automatically. Once the process completes, verify that the flags have been added. -For more details, see [Issue #183910]. +For more details, see Flutter [issue #183910][issue-183910]. -All add-to-app projects must manually add `android.builtInKotlin=false` -and `android.newDsl=false` to the Android host app's `gradle.properties` file. -The Flutter migrator tool cannot run during add-to-app Android host app builds +All add-to-app projects must manually add +`android.builtInKotlin=false` and `android.newDsl=false` to +the Android host app's `gradle.properties` file. +The Flutter migrator tool can't run during add-to-app Android host app builds because the host app is a pure native Android project. ```properties diff title="/gradle.properties" @@ -42,26 +51,26 @@ because the host app is a pure native Android project. :::note If your app doesn't apply -the `kotlin-android` plugin (also called Kotlin Gradle Plugin), -then you only need to add `android.newDsl=false` and do not need -further migration. +the `kotlin-android` plugin (also called the Kotlin Gradle Plugin), +then you only need to add `android.newDsl=false` and +don't need to complete any further migration steps. ::: -### Update the Gradle file +## Update the Gradle file -First, find the `kotlin-android` plugin (or the `org.jetbrains.kotlin.android` -plugin). +First, find the `kotlin-android` plugin +(or the `org.jetbrains.kotlin.android` plugin). It is likely located in the `plugins` block of the `/android/app/build.gradle` or the `/android/app/build.gradle.kts` file. If you use the legacy `apply` syntax, it will be located in -the Groovy-based `/android/app/build.gradle` file, as this syntax is -not supported in Kotlin DSL. +the Groovy-based `/android/app/build.gradle` file, +as this syntax is not supported in Kotlin DSL. -The following examples demonstrate how to migrate a Flutter Android app -and an add-to-app Android host app: +The following examples demonstrate how to +migrate a Flutter Android app and an add-to-app Android host app: -#### Migrate your Flutter Android app +### Migrate your Flutter Android app @@ -173,6 +182,7 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: // ... } ``` + Add the `kotlin.compilerOptions{}` DSL block with the following: ```groovy diff title="/android/app/build.gradle" @@ -207,7 +217,7 @@ kotlin { -#### Migrate your add-to-app Android host app +### Migrate your add-to-app Android host app Android native apps use the `alias` keyword to apply plugins, which is incompatible with the legacy `apply()` syntax. @@ -250,6 +260,7 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: // ... } ``` + Add the `kotlin.compilerOptions{}` DSL block with the following: ```kotlin diff title="/android/app/build.gradle.kts" @@ -283,75 +294,84 @@ kotlin { // ... ``` -### Validate +## Validate -Execute `flutter run` or `flutter build apk` to confirm that -your app builds and launches on a connected Android device or emulator. +Execute `flutter run` or `flutter build apk` to +confirm that your app builds and +launches on a connected Android device or emulator. -If your app fails to build because you are using an unmigrated Flutter plugin, +If your app fails to build because +you are using an unmigrated Flutter plugin, follow the instructions below: -### Report incompatible Kotlin Gradle Plugin usage to plugin authors +## Report incompatible Kotlin Gradle Plugin usage to plugin authors Follow these instructions only if your app uses a Flutter plugin -that has not yet migrated to built-in Kotlin. +that hasn't yet migrated to built-in Kotlin. -1. Find the repository of the unmigrated Flutter plugin by searching for the - plugin name on [pub.dev](https://pub.dev) or online. -2. Refer to the plugin CHANGELOG to confirm that no existing version - has migrated to built-in Kotlin. -3. Report an issue to the plugin authors, informing them that the Kotlin - Gradle Plugin is incompatible and won't be supported in a future version - of Flutter. +1. Find the repository of the unmigrated Flutter plugin by + searching for the plugin name on [pub.dev]({{site.pub}}) or online. +1. Check the plugin's changelog to confirm that + no existing version has migrated to built-in Kotlin. +1. Report an issue to the plugin authors, + informing them that the Kotlin Gradle Plugin is incompatible and + won't be supported in a future version of Flutter. You can use the following template for the issue: -**Issue Title:** Migrate Plugin to Built-in Kotlin +**Issue Title:** Migrate plugin to built-in Kotlin **Issue Body:** + +```markdown I am using `` in my Flutter app. Starting with Android Gradle Plugin (AGP) 9.0, support for applying the Kotlin Gradle Plugin (KGP) has been removed. -Because this plugin applies KGP, it causes a compilation error -that prevents my app from building. -Here is an example of the error [Issue #181383][]. +Because this plugin applies KGP, +it causes a compilation error that prevents my app from building. +Flutter [issue #181383](https://github.com/flutter/flutter/issues/181383) +includes an example of the error. Flutter has temporarily added support to allow KGP -while apps and plugins migrate to AGP 9.0+, +while apps and plugins migrate to AGP 9.0 or later, but this support will be removed in a future version of Flutter. -Please migrate this plugin to use built-in Kotlin to ensure your plugin -users can successfully build their apps in future versions of Flutter. +Please migrate this plugin to use built-in Kotlin to +ensure your plugin users can successfully +build their apps in future versions of Flutter. -Here is the Flutter [migration guide for plugin authors][plugin-migration-guide]. +Here is the Flutter +[migration guide for plugin authors](https://docs.flutter.dev/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors). +``` -Please be respectful and mindful of the plugin repository's rules and code -of conduct when reporting issues and interacting with plugin authors. +Please be respectful and mindful of the +plugin repository's rules and code of conduct when +reporting issues and interacting with plugin authors. For reference, see the [Flutter Code of Conduct][Code of Conduct]. +[Code of Conduct]: {{site.repo.flutter}}/blob/main/CODE_OF_CONDUCT.md + ## Next steps -See the [migration overview](./) for next steps. +For next steps, +see the [built-in Kotlin migration overview][migration-overview]. + +[migration-overview]: /release/breaking-changes/migrate-to-built-in-kotlin ## References Relevant issues: -- [Issue #183910][]: Add Disable Built-in Kotlin and new DSL Migrators -- [Issue #181383][]: Flutter plugins should support AGP 9.0.0 +- [Issue #183910][issue-183910]: Add Disable Built-in Kotlin and new DSL Migrators +- [Issue #181383][issue-181383]: Flutter plugins should support AGP 9.0.0 -The Gradle build files in your app vary based on the Flutter version -used when your app was created. +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 #183910]: {{site.github}}/flutter/flutter/issues/183910 -[Issue #181383]: {{site.github}}/flutter/flutter/issues/181383 +in your app's root directory. -[plugin-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors -[Code of Conduct]: https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md +[issue-183910]: {{site.repo.flutter}}/issues/183910 +[issue-181383]: {{site.repo.flutter}}/issues/181383 diff --git a/sites/docs/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md b/sites/docs/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md index a81251443c..67f5398f41 100644 --- a/sites/docs/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md +++ b/sites/docs/src/content/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors.md @@ -4,29 +4,35 @@ description: >- Migrate Flutter plugins to use built-in Kotlin. --- -## Migrate your Flutter plugin - This guide outlines the migration steps specifically for plugin authors. -### Update the Gradle file +:::note +To update Flutter apps to use built-in Kotlin, +follow the [migration guide for app developers][]. +::: + +[migration guide for app developers]: /release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers -The following steps assume you can update your plugin's Flutter SDK minimum -to 3.44. If you cannot update the Flutter SDK minimum to 3.44, follow the -instructions for -[supporting Flutter versions earlier than 3.44][flutter-sdk-minimum-below-3.44]. +## Update the Gradle file -First, find the `kotlin-android` plugin (or the `org.jetbrains.kotlin.android` -plugin). +The following steps assume you can +update your plugin's Flutter SDK minimum to 3.44. +If you can't update the Flutter SDK minimum to 3.44, +follow the instructions to +[support Flutter versions earlier than 3.44][flutter-sdk-minimum-below-3.44]. + +First, find the `kotlin-android` plugin +(or the `org.jetbrains.kotlin.android` plugin). It is likely located in the `plugins` block of the `/build.gradle` or the `/build.gradle.kts` file. -If you use the legacy `apply` syntax, it will be located in -the Groovy-based `/build.gradle` file, as this syntax is -not supported in Kotlin DSL. +If you use the legacy `apply` syntax, +it will be located in the Groovy-based `/build.gradle` file, +as this syntax isn't supported in Kotlin DSL. The following examples demonstrate how to migrate a Flutter plugin: - + **Before**: @@ -100,7 +106,7 @@ kotlin { ``` - + **Before**: @@ -135,6 +141,7 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: // ... } ``` + Add the `kotlin.compilerOptions{}` DSL block with the following: ```groovy diff title="/android/build.gradle" @@ -168,7 +175,9 @@ kotlin { -### Update the plugin's `pubspec.yaml` +[flutter-sdk-minimum-below-3.44]: #support-flutter-versions-earlier-than-3-44 + +## Update the plugin's `pubspec.yaml` Using the `kotlin.compilerOptions {}` DSL block requires a minimum Kotlin Gradle Plugin (KGP) version of 2.0.0. @@ -205,15 +214,18 @@ environment: # ... ``` -### Supporting Flutter versions earlier than 3.44 + + +## Support Flutter versions earlier than 3.44 -If you updated your plugin's Flutter SDK minimum to 3.44, skip this section -and proceed to [updating the plugin's `CHANGELOG.md`][update-plugin-changelog]. +If you updated your plugin's Flutter SDK minimum to 3.44, +skip this section and proceed to +[updating the plugin's `CHANGELOG.md`](#update-the-plugins-changelog). -If you cannot update the plugin's Flutter SDK minimum to 3.44, you must make -the following changes to `/android/build.gradle` or -`/android/build.gradle.kts` to support apps on AGP < 9 -and AGP >= 9: +If you can't update the plugin's Flutter SDK minimum to 3.44, you must +make the following changes to `/android/build.gradle` or +`/android/build.gradle.kts` to +support apps on AGP versions less than 9 and versions on 9 or later. @@ -256,14 +268,14 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: } ``` -Add a check to apply the Kotlin Gradle Plugin only when the app's Android -Gradle Plugin version is earlier than 9. +Add a check to apply the Kotlin Gradle Plugin only when +the app's Android Gradle Plugin version is less than version 9. ```kotlin diff title="/android/build.gradle.kts" + val agpMajor = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.substringBefore('.').toInt() + + if (agpMajor < 9) { -+ apply(plugin = "org.jetbrains.kotlin.android") ++ apply(plugin = "org.jetbrains.kotlin.android") + } ``` @@ -341,8 +353,8 @@ Next, remove the `kotlin-android` plugin and the `kotlinOptions` block: } ``` -Add a check to apply the Kotlin Gradle Plugin only when the app's Android -Gradle Plugin version is earlier than 9. +Add a check to apply the Kotlin Gradle Plugin only when +the app's Android Gradle Plugin version is less than version 9. ```groovy diff title="/android/build.gradle" + def agpMajor = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')[0] as int @@ -389,29 +401,31 @@ kotlin { -### Update the plugin's `CHANGELOG.md` + + +## Update the plugin's changelog -Include your changes in the CHANGELOG of the newly released plugin version: +Include your changes in the `CHANGELOG.md` file of +the newly released plugin version: ```markdown diff title="/CHANGELOG.md" + ## -+ - Updates minimum supported SDK version to Flutter 3.44/Dart 3.12. -+ - Migrates to built-in Kotlin ++ - Updates the minimum supported SDK version to Flutter 3.44/Dart 3.12. ++ - Migrates to built-in Kotlin. // ... ``` -### Validate +## Validate -Execute `flutter run` or `flutter build apk` to confirm that -your plugin example app builds and launches +Execute `flutter run` or `flutter build apk` to +confirm that your plugin example app builds and launches on a connected Android device or emulator. If your plugin example app also applies KGP, then you will also have to migrate the example app. -Follow the [migration guide for app developers][app-migration-guide] to migrate your example app. +To migrate your example app, +follow the [migration guide for app developers][app-migration-guide]. -[app-migration-guide]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers -[flutter-sdk-minimum-below-3.44]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors#supporting-flutter-versions-earlier-than-3-44 -[update-plugin-changelog]: {{site.flutter-docs}}/release/breaking-changes/migrate-to-built-in-kotlin/for-plugin-authors#update-the-plugins-changelogmd +[app-migration-guide]: /release/breaking-changes/migrate-to-built-in-kotlin/for-app-developers