diff --git a/firebase.json b/firebase.json index 305fbefa05..c74c584d2a 100644 --- a/firebase.json +++ b/firebase.json @@ -680,6 +680,7 @@ { "source": "/to/endorsed-federated-plugin", "destination": "/packages-and-plugins/developing-packages#endorsed-federated-plugin", "type": 301 }, { "source": "/to/federated-plugins", "destination": "/packages-and-plugins/developing-packages#federated-plugins", "type": 301 }, { "source": "/to/ffi-package", "destination": "/packages-and-plugins/developing-packages#plugin-ffi", "type": 301 }, + { "source": "/to/flutter-plugins-configuration", "destination": "/release/breaking-changes/flutter-plugins-configuration", "type": 301 }, { "source": "/to/flutter-fix", "destination": "/tools/flutter-fix", "type": 301 }, { "source": "/to/flutter-gradle-plugin-apply", "destination": "/release/breaking-changes/flutter-gradle-plugin-apply", "type": 301 }, { "source": "/to/flutter-test-docs", "destination": "https://api.flutter.dev/flutter/flutter_test/flutter_test-library.html", "type": 301 }, diff --git a/src/content/release/breaking-changes/flutter-plugins-configuration.md b/src/content/release/breaking-changes/flutter-plugins-configuration.md new file mode 100644 index 0000000000..41b3104478 --- /dev/null +++ b/src/content/release/breaking-changes/flutter-plugins-configuration.md @@ -0,0 +1,151 @@ +--- +title: .flutter-plugins-dependencies replaces .flutter-plugins. +description: >- + The deprecated `.flutter-plugins` tool file output has been replaced by + `.flutter-plugins-dependencies`, and any build scripts or references to it + must also be updated. +--- + +## Summary + +The `flutter` tool will no longer output the legacy `.flutter-plugins` metadata +file, and only output `.flutter-plugins-dependencies`. Tools and build scripts, +such as Gradle configurations (for Android apps) that rely on the presence of +`.flutter-plugins` will need to be updated. + +## Background + +[In 2019][PR 45379] `.flutter-plugins-dependencies` was added as a newer file +format that replaces `.flutter-plugins`. + +So a file that looked something like this: + +```txt +# This is .flutter-plugins +camera=/path/to/camera/plugin +shared_preferences=shared_preferences +``` + +... was replaced by something like this: + +```json +{ + "dependencyGraph": { + "camera": { + "name": "camera", + "version": "0.10.0", + "dependencies": { + "flutter": "0.0.0" + } + }, + "shared_preferences": { + "name": "shared_preferences", + "version": "2.0.15", + "dependencies": { + "flutter": "0.0.0" + } + } + }, + "flutter": { + "frameworkRevision": "3a0f99d4f2", + "channel": "stable" + } +} +``` + +Having both files output is a source of technical debt that complicates new +feature sets like not bundling `dev_dependency` plugins in a release app. + +## Migration guide + +Most Flutter developers don't parse or use this file, but build artifacts +(such as `settings.gradle`), as generated by older invocations of +`flutter create --platforms android`. These legacy files might still reference `.flutter-plugins` and +must be updated to a newer build script. + +For example: + +```groovy +include ':app' + +def flutterProjectRoot = rootProject.projectDir.parentFile.toPath() + +def plugins = new Properties() +// Note explicitly reading the legacy '.flutter-plugins' file. +def pluginsFile = new File(flutterProjectRoot.toFile(), '.flutter-plugins') +if (pluginsFile.exists()) { + pluginsFile.withReader('UTF-8') { reader -> plugins.load(reader) } +} + +plugins.each { name, path -> + def pluginDirectory = flutterProjectRoot.resolve(path).resolve('android').toFile() + include ":$name" + project(":$name").projectDir = pluginDirectory +} +``` + +... might be upgraded to its `settings.gradle.kts` equivalent: + +```kts +pluginManagement { + val flutterSdkPath = run { + val properties = java.util.Properties() + file("local.properties").inputStream().use { properties.load(it) } + val flutterSdkPath = properties.getProperty("flutter.sdk") + require(flutterSdkPath != null) { "flutter.sdk not set in local.properties" } + flutterSdkPath + } + + includeBuild("$flutterSdkPath/packages/flutter_tools/gradle") + + repositories { + google() + mavenCentral() + gradlePluginPortal() + } +} + +plugins { + // Note the use of the flutter-plugin-loader versus reading '.flutter-plugins' + id("dev.flutter.flutter-plugin-loader") version "1.0.0" + id("com.android.application") version "8.1.0" apply false + id("org.jetbrains.kotlin.android") version "1.8.22" apply false +} + +include(":app") +``` + +See [Deprecated imperative apply of Flutter's Gradle plugins][imperative-apply] +for details of switching to the newer plugin DSL. + +To smoke test whether your build relies on a `.flutter-plugins` file, you +can use the flag `--no-emit-legacy-flutter-plugins`: + +```sh +flutter build apk --no-emit-legacy-flutter-plugins +``` + +Any build tools or scripts that might rely on that file being output will now +fail. + +## Timeline + +Not released + +Not released + 1, `.flutter-plugins` support will be removed. + +## References + +Relevant Issues: + +- [Issue 48918][], where `.flutter-plugins` was (in 2020) slated for deprecation. + +Relevant PRs: + +- [PR 45379][], where `.flutter-plugins-dependencies` was originally added. +- [PR 157388][], where a warning was adding to the Flutter Android build scripts. + +[Issue 48918]: https://github.com/flutter/flutter/issues/48918 +[PR 45379]: https://github.com/flutter/flutter/pull/45379 +[PR 157388]: https://github.com/flutter/flutter/pull/157388 +[imperative-apply]: https://docs.flutter.dev/release/breaking-changes/flutter-gradle-plugin-apply diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index 67c99c2df2..1f7f44ccc3 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -33,12 +33,14 @@ release, and listed in alphabetical order: ### Not yet released to stable +* [`.flutter-plugins-dependencies` replaces `.flutter-plugins`][] * [`Color` wide gamut support][] * [Remove invalid parameters for `InputDecoration.collapsed`][] * [Stop generating `AssetManifest.json`][] * [Deprecate `TextField.canRequestFocus`][] * [Set default for SystemUiMode to Edge-to-Edge][] +[`.flutter-plugins-dependencies` replaces `.flutter-plugins`]: /release/breaking-changes/flutter-plugins-configuration [`Color` wide gamut support]: /release/breaking-changes/wide-gamut-framework [Remove invalid parameters for `InputDecoration.collapsed`]: /release/breaking-changes/input-decoration-collapsed [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json