Skip to content

Commit 88fe7f2

Browse files
[AGP 9.1.0 Migration #1] Add Android Gradle Plugin Public API migration documentation (flutter#190842)
There are 2 files in this pr. One is a document the ai used to keep track of work. More importantly it acts kind of like issues so it references the items in future prs. The second is user facing website documentation. I do not know if we will use it verbatim but for the set of prs lets treat that md doc as human understandable documentation that we must understand before landing the next pr. Reviewers: When the pr is out of draft and your comments are fully addressed please prioritize this pr over other work. The review bar is higher, the number of reviews has more people and the work for the next pr is already done. - @reidbaker --- Standard review context for this pr stack This is PR is part of an 11 pr stack to migrate the "newdsl" `gradle-api` specifically in agp 9.1.0. The complete stack has pass pre submits, post submits and customer tests. https://flutter-dashboard.appspot.com/#/build?repo=flutter&branch=experimental/agp-gradle-api All of the code was LLM authored. A mix of manual prompting, automatic prompting, several models and adversarial review. The combined sessions are enough that I cannot include relevant prompts like I have been doing on other prs. If you want to review the pr stack you can find it here. These prs will be abandoned/closed as prs land into flutter/flutter. 1. reidbaker-agent#1 (branch: agp-api-doc) 2. reidbaker-agent#2 (branch: agp-internal-utils) 3. reidbaker-agent#3 (branch: agp-buildmode-deps) 4. reidbaker-agent#4 (branch: agp-plugin-buildtypes) 5. reidbaker-agent#5 (branch: agp-ndk-fallback) 6. reidbaker-agent#6 (branch: agp-assets-onvariants) 7. reidbaker-agent#7 (branch: agp-apk-copy-versioncode) 8. reidbaker-agent#8 (branch: agp-add-to-app) 9. reidbaker-agent#9 (branch: agp-aar-script) 10. reidbaker-agent#10 (branch: agp-newdsl-flip) 11. reidbaker-agent#11 (branch: agp-gradle-api) Follow up work is tracked in flutter#190964 This work is urgent in the sense that we are worried that android will publish agp 10 with no opt out but not so urgent that we are willing to break flutter users because we didn't review or understand the code because we were in a rush. Breaking changes are expected as part of this work. There are patterns the android team explicitly does not want apps to use and apis that have no equivalent. As part of the effort to ensure this work does not slip into ai slop, prs from this stack will be reviewed by me (@reidbaker) before asking for review. Then we will have 2 android expert reviewers also review the every pr. --- Agent authored pr description This is PR 1 of 11 in the AGP 9.1.0 / public `gradle-api` migration stack. It adds the contributor-facing and website draft documentation for the Flutter Gradle Plugin's migration to the Android Gradle Plugin public Variant API, which unblocks building Flutter Android apps with AGP's `newDsl=true` enabled. Part of flutter#180137 and flutter#166550. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. --------- Co-authored-by: reidbaker-agent <[email protected]>
1 parent d5c92ab commit 88fe7f2

2 files changed

Lines changed: 419 additions & 0 deletions

File tree

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
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

Comments
 (0)