From eda7f563de797c167a6d6fc76f6587700e41d1ad Mon Sep 17 00:00:00 2001 From: Bartek Pacia Date: Fri, 8 Dec 2023 06:36:42 +0100 Subject: [PATCH] Start writing migration guide for Gradle plugin apply (#9857) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR adds a guide explaining how to migrate from _imperative apply_ of Flutter's Gradle plugins to _declarative apply_. Resolves https://github.com/flutter/flutter/issues/135392 ## Presubmit checklist - [x] This PR doesn’t contain automatically generated corrections (Grammarly or similar). - [x] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style) — for example, it doesn’t use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person). - [x] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer. ## Preview [here](https://flutter-docs-prod--pr9857-migration-guide-gradle-plugi-vyllekcb.web.app/release/breaking-changes/flutter-gradle-plugin-apply) --------- Co-authored-by: Anthony Sansone Co-authored-by: Gustl22 --- .../flutter-gradle-plugin-apply.md | 208 ++++++++++++++++++ src/release/breaking-changes/index.md | 1 + 2 files changed, 209 insertions(+) create mode 100644 src/release/breaking-changes/flutter-gradle-plugin-apply.md diff --git a/src/release/breaking-changes/flutter-gradle-plugin-apply.md b/src/release/breaking-changes/flutter-gradle-plugin-apply.md new file mode 100644 index 0000000000..c3917fdb19 --- /dev/null +++ b/src/release/breaking-changes/flutter-gradle-plugin-apply.md @@ -0,0 +1,208 @@ +--- +title: Deprecated imperative apply of Flutter's Gradle plugins +description: > + How to migrate your Android app's Gradle build files to the new, declarative + format. +--- + +## Summary + +To build a Flutter app for Android, Flutter's Gradle plugins must be applied. +Historically, this was done imperatively with Gradle's +[legacy, imperative apply script method][]. + +In Flutter 3.16, support has been added for applying these plugins with Gradle's +[declarative plugins {} block][] (also called the Plugin DSL) and it is +now the recommended approach. Since Flutter 3.16, projects generated with +`flutter create` use the Plugin DSL to apply Gradle plugins. Projects created +with versions of Flutter prior to 3.16 need to be migrated manually. + +Applying Gradle plugins using the `plugins {}` block executes the same code as +before and should produce equivalent app binaries. + +To learn about advantages the new Plugin DSL syntax has over the legacy `apply` +script syntax, see [Gradle docs][plugins block]. + +Migrating the app ecosystem to use the new approach will also make it easier for +Flutter team to develop Flutter's Gradle plugins, and to enable exciting new +features in the future, such as using Kotlin instead of Groovy in Gradle +buildscripts. + +## Migrate + +### android/settings.gradle + +Replace the contents of `/android/settings.gradle` with the below, +remembering to replace `{{agpVersion}}` and `{{kotlinVersion}}` with previously +used values: + +```gradle +pluginManagement { + def flutterSdkPath = { + def properties = new Properties() + file("local.properties").withInputStream { properties.load(it) } + def flutterSdkPath = properties.getProperty("flutter.sdk") + assert flutterSdkPath != null, "flutter.sdk not set in local.properties" + return flutterSdkPath + } + settings.ext.flutterSdkPath = flutterSdkPath() + + includeBuild("${settings.ext.flutterSdkPath}/packages/flutter_tools/gradle") + + repositories { + google() + mavenCentral() + gradlePluginPortal() + } +} + +plugins { + id "dev.flutter.flutter-plugin-loader" version "1.0.0" + id "com.android.application" version "{{agpVersion}}" apply false + id "org.jetbrains.kotlin.android" version "{{kotlinVersion}}" apply false +} + +include ":app" +``` + +If you made some changes to this file, make sure they're placed after +`pluginManagement {}` and `plugins {}` blocks, since Gradle enforces that no +other code may be placed before these blocks. + +### android/build.gradle + +Remove the whole `buildscript` block from `/android/app/build.gradle`. First, +remove these 2 chunks of code that use the legacy imperative apply method: + +```diff +-def flutterRoot = localProperties.getProperty('flutter.sdk') +-if (flutterRoot == null) { +- throw new GradleException("Flutter SDK not found. Define location with flutter.sdk in the local.properties file.") +-} +``` + +```diff +-apply plugin: 'com.android.application' +-apply plugin: 'kotlin-android' +-apply from: "$flutterRoot/packages/flutter_tools/gradle/flutter.gradle" +``` + +Now apply the plugins again, but this time using the Plugin DSL syntax. At the +very top of your file, add: + +```diff ++plugins { ++ id "com.android.application" ++ id "kotlin-android" ++ id "dev.flutter.flutter-gradle-plugin" ++} +``` + +### Validation + +Execute `flutter run` to confirm your app builds and launches on a connected +Android device or emulator. + +## Examples + +### Google Mobile Services and Crashlytics + +If your app was using Google Mobile Services and Crashlytics, remove the +following lines from `/android/build.gradle`: + +```diff + buildscript { + // ... + + dependencies { + // ... +- classpath "com.google.gms:google-services:4.4.0" +- classpath "com.google.firebase:firebase-crashlytics-gradle:2.9.9" + } + } +``` + +and remove these 2 lines from `/android/app/build.gradle`: + +```diff +-apply plugin: 'com.google.gms.google-services' +-apply plugin: 'com.google.firebase.crashlytics' +``` + +To migrate to the new, declarative apply of the GMS and Crashlytics plugins, add +the following lines to `/android/settings.gradle`: + +```diff + plugins { + id "dev.flutter.flutter-plugin-loader" version "1.0.0" + id "com.android.application" version "{{agpVersion}}" apply false + id "org.jetbrains.kotlin.android" version "{{kotlinVersion}}" apply false ++ id "com.google.gms.google-services" version "4.4.0" apply false ++ id "com.google.firebase.crashlytics" version "2.9.9" apply false + } +``` + +and the following lines to `/android/app/build.gradle` (remembering to +replace `{{agpVersion}}` and `{{kotlinVersion}}` with previously used values): + +```diff + plugins { + id "com.android.application" + id "dev.flutter.flutter-gradle-plugin" + id "org.jetbrains.kotlin.android" ++ id "com.google.gms.google-services" ++ id "com.google.firebase.crashlytics" + } +``` + +## References + +Gradle build files generated by `flutter create` differ across Flutter versions. +For a detailed overview, see [issue #135392][]. You should consider using the +latest versions of build files. + +[legacy, imperative apply script method]: https://docs.gradle.org/8.5/userguide/plugins.html#sec:script_plugins +[declarative plugins {} block]: https://docs.gradle.org/8.5/userguide/plugins.html#sec:plugins_block +[plugins block]: https://docs.gradle.org/current/userguide/plugins.html#plugins_dsl_limitations +[issue #135392]: https://github.com/flutter/flutter/issues/135392 diff --git a/src/release/breaking-changes/index.md b/src/release/breaking-changes/index.md index 23370877a1..37e31b8590 100644 --- a/src/release/breaking-changes/index.md +++ b/src/release/breaking-changes/index.md @@ -40,6 +40,7 @@ release, and listed in alphabetical order: [Deprecate `TextField.canRequestFocus`]: {{site.url}}/release/breaking-changes/can-request-focus [Accessibility traversal order of tooltip changed]: {{site.url}}/release/breaking-changes/tooltip-semantics-order [Default multitouch scrolling]: {{site.url}}/release/breaking-changes/multi-touch-scrolling +[Deprecate imperative apply of Flutter's Gradle plugins]: ${{ site.url }}/release/breaking-changes/flutter-gradle-plugin-apply ### Released in Flutter 3.16