From 6fbd62f33e44cba5a71b9c7253e7679ae09187ce Mon Sep 17 00:00:00 2001 From: Matan Lurey Date: Thu, 31 Oct 2024 10:34:19 -0700 Subject: [PATCH] Declare `package:flutter_gen` to be deprecated (#11343) Declare the `package:flutter_gen` approach deprecated and explain the current migration path. Part of https://github.com/flutter/flutter/issues/157819, https://github.com/flutter/flutter/issues/102983. /cc @andrewkolos --------- Co-authored-by: Jonah Williams Co-authored-by: Chris Bracken --- firebase.json | 1 + .../flutter-generate-i10n-source.md | 90 +++++++++++++++++++ .../flutter-plugins-configuration.md | 4 +- src/content/release/breaking-changes/index.md | 2 + 4 files changed, 95 insertions(+), 2 deletions(-) create mode 100644 src/content/release/breaking-changes/flutter-generate-i10n-source.md diff --git a/firebase.json b/firebase.json index 020e02637b..70d0990d4d 100644 --- a/firebase.json +++ b/firebase.json @@ -683,6 +683,7 @@ { "source": "/to/et", "destination": "https://flutter.dev/to/engine-tool", "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-gen-deprecation", "destination": "/release/breaking-changes/flutter-generate-i10n-source", "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 }, diff --git a/src/content/release/breaking-changes/flutter-generate-i10n-source.md b/src/content/release/breaking-changes/flutter-generate-i10n-source.md new file mode 100644 index 0000000000..be2fe4947e --- /dev/null +++ b/src/content/release/breaking-changes/flutter-generate-i10n-source.md @@ -0,0 +1,90 @@ +--- +title: Localized messages are generated into source, not a synthetic package. +description: >- + When using `package:flutter_localizations`, the default generated location + (and eventually, only possible location) is within your source (`lib/`) + directory, and not the synthetic package `package:flutter_gen`. +--- + +## Summary + +The `flutter` tool will no longer generate a synthetic `package:flutter_gen` +or modify the `package_config.json` of the application. Applications or tools +that previously referenced `package:flutter_gen` will instead reference source +files generated into the application directly. + +## Background + +`flutter_gen` is a virtual (synthetic) package that is created by the `flutter` +command-line tool to allow developers to import that package to access generated +symbols and functionality, such as for +[internationalization][Internationalizing Flutter apps]. As the package is not +listed in an app's `pubspec.yaml`, and is created via re-writing the (generated) +`package_config.json`, numerous problems have been created. + +## Migration Guide + +This change only effects users that have the following in their `pubspec.yaml`: + +```yaml +flutter: + generate: true +``` + +A synthetic package (`package:flutter_gen`) is created and referenced by the +application: + +```dart +import 'package:flutter_gen/gen_l10n/app_localizations.dart'; +// ... +const MaterialApp( + title: 'Localizations Sample App', + localizationsDelegates: AppLocalizations.localizationsDelegates, + supportedLocales: AppLocalizations.supportedLocales, +); +``` + +There are two ways to migrate away from importing `package:flutter_gen`: + +1. Specify `synthetic-package: false` in the accompanying [l10n.yaml][] file: + + ```yaml + synthetic-package: false + + # The files are generated into the path specified by `arb-dir` + arb-dir: lib/i18n + + # Or, specifically provide an output path: + output-dir: lib/src/generated/i18n + ``` + +2. Pass `--no-implicit-pubspec-resolution` to invocations of the `flutter` tool: + + ```sh + flutter run --no-implicit-pubspec-resolution + ``` + +## Timeline + +Not released + +Not released + 1, `package:flutter_gen` support will be removed. + +## References + +Relevant Issues: + +- [Issue 73870][], where `package:flutter_gen` pub problems are first found. +- [Issue 102983][], where `package:flutter_gen` problems are outlined. +- [Issue 157819][], where `--implicit-pubspec-resolution` is discussed. + +Relevant Articles: + +- [Internationalizing Flutter apps][], the canonical documentation for the + feature. + +[l10n.yaml]: https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization#configuring-the-l10n-yaml-file +[Issue 73870]: https://github.com/flutter/flutter/issues/73870 +[Issue 102983]: https://github.com/flutter/flutter/issues/102983 +[Issue 157819]: https://github.com/flutter/flutter/issues/157819 +[Internationalizing Flutter apps]: https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization#adding-your-own-localized-messages diff --git a/src/content/release/breaking-changes/flutter-plugins-configuration.md b/src/content/release/breaking-changes/flutter-plugins-configuration.md index 562828065b..cda0b05bd8 100644 --- a/src/content/release/breaking-changes/flutter-plugins-configuration.md +++ b/src/content/release/breaking-changes/flutter-plugins-configuration.md @@ -119,10 +119,10 @@ 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`: +can use the flag `--no-implicit-pubspec-resolution`: ```sh -flutter build apk --no-emit-legacy-flutter-plugins +flutter build apk --no-implicit-pubspec-resolution ``` Any build tools or scripts that might rely on that file being output will now diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index 94e9dd33c1..91c2ba19c7 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -33,6 +33,7 @@ release, and listed in alphabetical order: ### Not yet released to stable +* [Localized messages are generated into source, not a synthetic package][] * [`.flutter-plugins-dependencies` replaces `.flutter-plugins`][] * [`Color` wide gamut support][] * [Remove invalid parameters for `InputDecoration.collapsed`][] @@ -41,6 +42,7 @@ release, and listed in alphabetical order: * [Set default for SystemUiMode to Edge-to-Edge][] * [Deprecate `ThemeData.dialogBackgroundColor` in favor of `DialogThemeData.backgroundColor`][] +[Localized messages are generated into source, not a synthetic package]: /release/breaking-changes/flutter-generate-i10n-source [`.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