|
| 1 | +# Migrating the Flutter Gradle Plugin to the AGP Public API Surface |
| 2 | + |
| 3 | +This document is the contributor-facing record of the migration of the Flutter |
| 4 | +Gradle Plugin (FGP) off the legacy Android Gradle Plugin (AGP) DSL/Variant API |
| 5 | +and AGP internals, onto the public API surface shipped in the |
| 6 | +`com.android.tools.build:gradle-api` artifact. |
| 7 | + |
| 8 | +Umbrella issues: |
| 9 | + |
| 10 | +- newDsl flip: https://github.com/flutter/flutter/issues/180137 |
| 11 | +- Variant API migration: https://github.com/flutter/flutter/issues/166550 |
| 12 | + |
| 13 | +The user-facing breaking-change page draft lives next to this file in |
| 14 | +[`website-page-draft.md`](website-page-draft.md). It must be published to |
| 15 | +`docs.flutter.dev/release/breaking-changes/` before the newDsl flip (phase P9) |
| 16 | +reaches the beta channel. |
| 17 | + |
| 18 | +## Why |
| 19 | + |
| 20 | +AGP 9 (January 2026) deprecated the old DSL and Variant APIs behind the |
| 21 | +`android.newDsl=false` escape hatch. AGP 10 (late 2026) removes those APIs |
| 22 | +entirely **and** removes access to AGP internals — only the public surface of |
| 23 | +the `gradle-api` artifact remains. Today the FGP: |
| 24 | + |
| 25 | +- compiles against the FULL `com.android.tools.build:gradle` artifact |
| 26 | + (`packages/flutter_tools/gradle/build.gradle.kts`); |
| 27 | +- uses the legacy variant API (`applicationVariants`, `libraryVariants`, |
| 28 | + `variant.outputs`, `assembleProvider`, `packageApplicationProvider`, |
| 29 | + `versionCodeOverride`); |
| 30 | +- uses the legacy `BaseExtension` |
| 31 | + (`FlutterPluginUtils.getLegacyAndroidExtension`); |
| 32 | +- imports one internal DSL class (`com.android.build.gradle.internal.dsl.BuildType` |
| 33 | + in `plugins/PluginHandler.kt`); |
| 34 | +- imports one internal utility |
| 35 | + (`com.android.build.gradle.internal.utils.getKotlinAndroidPluginVersion` in |
| 36 | + `VersionFetcher.kt`); |
| 37 | +- drives `flutter build aar` with legacy dynamic Groovy in |
| 38 | + `aar_init_script.gradle`. |
| 39 | + |
| 40 | +Flutter templates pin AGP 9.1.0 but ship `android.newDsl=false`, and a tool |
| 41 | +migrator (`disable_new_dsl_migration.dart`) adds the opt-out to existing |
| 42 | +projects. That opt-out dies with AGP 10. |
| 43 | + |
| 44 | +## End state |
| 45 | + |
| 46 | +- The FGP uses only public APIs and compiles against `gradle-api`. |
| 47 | +- Templates no longer ship `android.newDsl=false`. |
| 48 | +- The opt-out **add** migrator is replaced by a **removal** migrator that |
| 49 | + deletes only the Flutter-added opt-out lines. |
| 50 | +- A fresh `flutter create` app builds with newDsl on. |
| 51 | + |
| 52 | +## Decision records |
| 53 | + |
| 54 | +1. **Min AGP floor: out of scope.** A separate version bump owned the |
| 55 | + floor, which has now landed on `master` (PRs #176858 and #177416 bumped the |
| 56 | + floor to `8.11.1`). This migration builds seamlessly on that new floor. |
| 57 | + Every replacement API used here was verified public in `gradle-api:8.11.1` |
| 58 | + (decompiled jar inspection). If implementation finds a replacement API that |
| 59 | + genuinely requires a higher min AGP: document which API and why no |
| 60 | + compatible alternative exists in this file, then bump — otherwise version |
| 61 | + floors are untouched by this work. |
| 62 | +2. **"Public in 8.x" does not mean binary-compatible on 9.x.** |
| 63 | + `AgpCommonExtensionWrapper.kt` exists precisely because the public |
| 64 | + `CommonExtension` broke between AGP 8 and 9. Mitigation: a CI/test axis |
| 65 | + compiling the FGP against gradle-api 9.x is mandatory from phase P2 onward, |
| 66 | + plus a bytecode check (javap grep) that no compiled FGP class references |
| 67 | + `CommonExtension` as an owner. |
| 68 | +3. **`android.builtInKotlin=false` stays out of scope.** Flipping it requires |
| 69 | + the separate built-in-Kotlin migration workstream. Users get a second |
| 70 | + (smaller) gradle.properties churn later; the breaking-change page states |
| 71 | + this explicitly. Corollary: the P9 removal migrator must anchor on the |
| 72 | + `android.newDsl` property line — never on marker-comment wording alone — |
| 73 | + because the template's builtInKotlin marker comment is nearly identical. |
| 74 | +4. **Per-ABI versionCode mechanism.** Do NOT re-implement AGP's flavor-merge |
| 75 | + precedence via a `finalizeDsl` snapshot. Preferred mechanism (spiked first |
| 76 | + in P6): read-then-set on `VariantOutput.versionCode` inside `onVariants` — |
| 77 | + it is seeded with the merged value; set `abiOffset * 1000 + current`, |
| 78 | + avoiding a self-referential `.map`. Fall back to a snapshot only if |
| 79 | + read-then-set is impossible; record the outcome here. |
| 80 | + - *Spike result:* _pending (P6)_. |
| 81 | +5. **`buildModeFor` semantics.** Every variant-scope call uses the |
| 82 | + `(name, debuggable)` overload with the public `Component.debuggable`. |
| 83 | + Name-based inference is confined to the one DSL-scope case with no public |
| 84 | + signal (the library-plugin build-type copy in `PluginHandler`). This |
| 85 | + preserves add-to-app custom-debuggable matching (a host `staging` |
| 86 | + debuggable build type maps to debug engine artifacts). |
| 87 | + |
| 88 | +## Replacement map |
| 89 | + |
| 90 | +| Legacy usage | Where | Public replacement | Phase | |
| 91 | +| --- | --- | --- | --- | |
| 92 | +| `internal.utils.getKotlinAndroidPluginVersion` | `VersionFetcher.kt` | delete; rely on existing fallback chain (`kotlin_version` property → `KotlinAndroidPluginWrapper.pluginVersion` → reflection); null when KGP absent is OK | P1 | |
| 93 | +| `compileSdkVersion` string compare (`"android-NN"` substring) | `FlutterPluginUtils.getCompileSdkFromProject`, `PluginHandler` warning | wrapper `compileSdk` / `compileSdkPreview`; numeric compare with defined preview semantics | P1 | |
| 94 | +| `BaseExtension.ndkVersion` | `FlutterPluginUtils.getConfiguredNdkVersion` | wrapper `ndkVersion` | P1 | |
| 95 | +| `buildModeFor(BuildType)` (legacy model type) | `FlutterPluginUtils.kt` | `buildModeFor(name, debuggable)` overload | P2 | |
| 96 | +| `getLegacyAndroidExtension(project).buildTypes` loops | `PluginHandler.kt` | wrapper new-DSL `buildTypes` container | P2 | |
| 97 | +| `internal.dsl.BuildType` live aliasing into plugin projects | `PluginHandler.kt` | `initWith`-based copy on new-DSL `BuildType`; app-specific props only when both sides are `ApplicationBuildType` | P3 | |
| 98 | +| `BaseExtension` / `getLegacyAndroidExtension` (remaining call sites) | `FlutterPluginUtils.kt` | wrapper accessors incl. `externalNativeBuild` | P4 | |
| 99 | +| eager `applicationVariants.configureEach` task creation; mergeAssets/processResources hooks | `FlutterPlugin.kt`, `FlutterPluginUtils.kt` | consolidated `onVariants` block; `CopyFlutterAssetsTask` + `variant.sources.assets.addGeneratedSourceDirectory` | P5 | |
| 100 | +| `variant.outputs` + `packageApplicationProvider` + `doLast` APK copy; `versionCodeOverride` | `FlutterPluginUtils.kt` | `CopyFlutterApksTask` (`SingleArtifact.APK` + `BuiltArtifactsLoader`); read-then-set `VariantOutput.versionCode` | P6 | |
| 101 | +| `libraryVariants.all` × host `applicationVariants.all` cross-wiring | `FlutterPlugin.kt` (add-to-app) | library-side `onVariants` with `Component.debuggable`; no host-project lookup | P7 | |
| 102 | +| dynamic Groovy legacy API in `aar_init_script.gradle` | `aar_init_script.gradle` | `components`-based enumeration; ext-property guard | P8 | |
| 103 | +| `android.newDsl=false` template/migrator | templates, `disable_new_dsl_migration.dart` | drop from templates; `RemoveNewDslOptOutMigration` | P9 | |
| 104 | +| FULL `gradle` artifact dependency | `build.gradle.kts` | `gradle-api` artifact (compile-time proof of zero internal usage) | P10 | |
| 105 | + |
| 106 | +## Phase map |
| 107 | + |
| 108 | +Each phase is one PR-sized change on its own branch. P8 is an independent lane |
| 109 | +(Groovy script, disjoint files); P0/P1 are disjoint from each other; everything |
| 110 | +else serializes through `FlutterPlugin.kt` / `FlutterPluginUtils.kt`. |
| 111 | + |
| 112 | +| Phase | Branch | Size | Summary | |
| 113 | +| --- | --- | --- | --- | |
| 114 | +| P0 | `agp-api-doc` | S | this doc + website page draft | |
| 115 | +| P1 | `agp-internal-utils` | S | VersionFetcher internal util removal; numeric compileSdk compare; ndkVersion via wrapper | |
| 116 | +| P2 | `agp-buildmode-deps` | M | `buildModeFor` overloads; new-DSL flutter dependencies; 9.x compile axis | |
| 117 | +| P3 | `agp-plugin-buildtypes` | M | `initWith` copy for plugin build types; drop internal import; internal-import lint | |
| 118 | +| P4 | `agp-ndk-fallback` | S | delete `BaseExtension`; externalNativeBuild via wrapper | |
| 119 | +| P5 | `agp-assets-onvariants` | L | lazy task registration (5a) + generated-asset-dir wiring (5b) | |
| 120 | +| P6 | `agp-apk-copy-versioncode` | L | `CopyFlutterApksTask`; per-ABI versionCode; app path legacy-free | |
| 121 | +| P7 | `agp-add-to-app` | L | library-side `onVariants`; delete host cross-wiring + P5a legacy fork | |
| 122 | +| P8 | `agp-aar-script` | M | aar_init_script public-API cleanup | |
| 123 | +| P9 | `agp-newdsl-flip` | M | templates drop opt-out; removal migrator; new error handlers | |
| 124 | +| P10 | `agp-gradle-api` | M | dependency swap to `gradle-api`; test migration | |
| 125 | + |
| 126 | +## Cross-cutting rules |
| 127 | + |
| 128 | +- **R1 Lockstep:** any PR changing FGP-emitted message text updates the |
| 129 | + matching `gradle_errors.dart` matcher and its Dart test in the same PR. |
| 130 | +- **R2 Revert notes:** each PR description carries "revert-safe until phase X |
| 131 | + lands"; once superseded, policy is fix-forward. At least one full post-submit |
| 132 | + CI soak between dependent phases (no same-day stacking of P2–P4). |
| 133 | +- **R3 9.x axis:** from P2, gradle unit tests additionally compile against |
| 134 | + gradle-api 9.x in CI, plus the javap `CommonExtension` bytecode check. |
| 135 | +- **R4 Config-cache:** master baseline established first; the per-phase |
| 136 | + assertion is "no NEW config-cache violations", not full reuse. |
| 137 | +- **R5 Internal-import lint:** once P3 lands, a checked-in test forbids |
| 138 | + `com.android.build.gradle.internal.*` imports in `src/main`. |
| 139 | +- **R6 Staged newDsl=true axis:** app flows green from end of P6; add-to-app |
| 140 | + from P7; aar from P8. The full matrix is the P9 gate. |
| 141 | + |
| 142 | +## Revert-window table |
| 143 | + |
| 144 | +| Phase | Revert window | |
| 145 | +| --- | --- | |
| 146 | +| P0 | always revert-safe | |
| 147 | +| P1–P4 | each until the next phase in the chain lands; then fix-forward | |
| 148 | +| P5 | until P6 lands | |
| 149 | +| P6 / P7 | mutually tolerant (disjoint app/module paths) until P10 | |
| 150 | +| P8 | revert-safe even after P10, but not after P9 | |
| 151 | +| P9 | cleanly revertible in isolation | |
| 152 | +| P10 | cleanly revertible in isolation | |
| 153 | + |
| 154 | +## Features that must break (tracked; updated as implementation learns) |
| 155 | + |
| 156 | +1. **User build scripts using legacy APIs** (`applicationVariants.all` |
| 157 | + APK-rename recipes) fail under newDsl — the biggest break. Mitigated by new |
| 158 | + error handlers (P9) and the website page. |
| 159 | +2. **flutter-apk copy**: same names/paths (`app[-abi][-flavor]-<mode>.apk`, |
| 160 | + byte-matching the current concatenation order), but an UP-TO-DATE-capable |
| 161 | + finalizer task replaces the `doLast` block; new task names appear in |
| 162 | + `gradlew tasks`. |
| 163 | +3. **Per-ABI versionCode**: post-`finalizeDsl` user mutations (`afterEvaluate` |
| 164 | + CI patterns) may behave differently; a runtime divergence warning is added. |
| 165 | +4. **Custom build types → plugins**: live-aliased instances become `initWith` |
| 166 | + copies; library plugins cannot receive `isDebuggable` (no public setter on |
| 167 | + `LibraryBuildType`). **Warning:** If an app uses a custom build type (like `staging`), |
| 168 | + the plugin's `BuildConfig.DEBUG` and native (C++/JNI) code may silently compile |
| 169 | + in release mode instead of debug mode. Matching is preserved via `matchingFallbacks`, |
| 170 | + but C++ debugging will be broken for those custom build types. |
| 171 | +5. **Asset merge**: flutter assets become a merged source dir instead of a |
| 172 | + post-merge overwrite; collisions resolve by AGP source-set priority. |
| 173 | +6. **Add-to-app**: the explicit `:app:merge<V>Assets.dependsOn` edge and |
| 174 | + host-project lookup are removed; `flutter.hostAppProjectName` becomes a |
| 175 | + no-op with a deprecation warning naming a removal milestone. Build scripts that |
| 176 | + reference Flutter's `copyFlutterAssets<V>` tasks by name (e.g. `tasks.getByPath(...)`) |
| 177 | + will crash with a `Task with path ... not found` error because the tasks are now |
| 178 | + registered lazily. |
| 179 | +7. **Task realization/type**: flutter tasks become lazy `TaskProvider`s, and |
| 180 | + `copyFlutterAssets<V>` changes type from `org.gradle.api.tasks.Copy` to a |
| 181 | + custom task class — `tasks.named(..., Copy::class)` casts fail. |
| 182 | +8. **`flutter build aar`**: the singleVariant dedup guard becomes an |
| 183 | + ext-property/try-catch with a specified error message; variant enumeration |
| 184 | + moves from `libraryVariants` to `components` — partial user `singleVariant` |
| 185 | + declarations surface differently. |
| 186 | +9. **newDsl flip**: new projects lose the opt-out; the removal migrator deletes |
| 187 | + only marker-tagged `android.newDsl` lines (template marker "This newDsl flag |
| 188 | + was added by the Flutter template"; migrator marker "This newDsl flag was |
| 189 | + added automatically by Flutter migrator"), anchored on the property line so |
| 190 | + the adjacent builtInKotlin lines are never touched; hand-added opt-outs are |
| 191 | + respected. |
| 192 | +10. **compileSdk mismatch warning** becomes a numeric compare with defined |
| 193 | + preview-vs-numeric semantics; the message keeps a distinctive substring of |
| 194 | + the old phrasing for searchability. |
| 195 | + |
| 196 | +## Verification matrix |
| 197 | + |
| 198 | +Full matrix at P6, P7, P9, P10; targeted per-phase otherwise. |
| 199 | + |
| 200 | +1. `cd packages/flutter_tools/gradle && ./gradlew test` (+ the R3 9.x axis) |
| 201 | +2. Targeted `integration.shard` tests named in each phase |
| 202 | +3. Scratch-app matrix: apk/appbundle × 3 modes; `--flavor`; `--split-per-abi` |
| 203 | + (+ apkanalyzer versionCode assertions, including the |
| 204 | + flavor-defined-versionCode case); `--deferred-components`; plugin with a |
| 205 | + custom build type; `flutter build aar`; add-to-app source & AAR host flows; |
| 206 | + `flutter run` / hot restart / `flutter attach`; Windows smoke for the copy |
| 207 | + tasks |
| 208 | +4. AGP axis: current floor AND 9.1 + `newDsl=false`; staged `newDsl=true` per R6 |
| 209 | +5. Config-cache per R4 |
0 commit comments