Repository navigation
Commit 8608bc9
[AGP 9.1.0 Migration flutter#7] Migrate the flutter-apk copy and per-ABI versionCode to the variant API (flutter#193693)
## Description
This is PR 7 of 11 in the AGP 9.1.0 / public `gradle-api` migration
stack ([flutter#180137](flutter#180137),
[flutter#166550](flutter#166550)).
This pr changes the way splitting by api version codes work. This can be
a surprising change but I have not found a work around.
PR 8 adds add-to-app support and as a result deletes a bunch of code
that exists to bridge the partial migration. See
flutter#19371 specifically
https://github.com/flutter/flutter/pull/193717/changes/f668780fd47caca13c03828f49d21572074825d6..a6be16034c8a1a4a0456cd35194b5973cfd4dc75#r4185414230
which is a subset of changes.
<details>
<summary>Agent authored details</summary>
### Changes
1. **flutter-apk copy on the variant API.** `CopyFlutterApksTask`
(`copyFlutterApks<Variant>`) copies the variant's `SingleArtifact.APK`
outputs, read through `BuiltArtifactsLoader`, into
`build/app/outputs/flutter-apk/`. The names are
`app[-abi][-flavor]-<mode>.apk`, the format `listApkPaths` in
`lib/src/android/gradle.dart` expects. `assemble<Variant>` depends on
the task.
- The task has no `Project` or variant fields. It uses injected
`FileSystemOperations` and `@InputDirectory @PathSensitive(RELATIVE)`.
- It is annotated `@DisableCachingByDefault(because = "Not worth
caching")`, the annotation and reason Gradle uses on its own `Copy` and
`Sync` tasks.
- Its declared outputs are the individual APK files (`@OutputFiles`).
The shared `flutter-apk` directory is not declared, because it would
overlap between variants.
- One naming function, `CopyFlutterApksTask.apkFileName`, produces both
the declared outputs and the copied files. Its inputs are the ABIs of
the variant's outputs, the flavor, and the build mode.
2. **Per-ABI versionCode without reading `output.versionCode`.** For
`--split-per-abi`, the plugin sets `output.versionCode =
ABI_VERSION[abi] * 1000 + base` on each `ApplicationVariant` output with
an ABI filter. It never reads the property, because AGP rejects that
read during configuration when
`android.compatibility.enableLegacyApi=false`.
- `DslVersionCodes` takes a snapshot of `defaultConfig.versionCode` and
each product flavor's `versionCode` in `androidComponents.finalizeDsl`.
- `forVariant(variant.productFlavors)` resolves the base the way AGP
merges it: the first flavor, in dimension order, that sets a
versionCode, otherwise `defaultConfig`.
- If the DSL declares no versionCode, Flutter logs a warning and leaves
the variant's versionCodes unchanged.
3. **APK transform errors point at the transform.** The copy fails in
two cases. Both can happen only if another plugin or build script
transforms `SingleArtifact.APK`:
- the APK directory has no `output-metadata.json`;
- an APK has an ABI filter that none of the variant's outputs declares.
Both error messages name `SingleArtifact.APK` and tell the user to
contact the maintainer of the plugin that does the transform. They do
not ask for a Flutter issue. The task KDoc and `website-page-draft.md`
say what a transform must keep. Plugins Flutter developers commonly use
(Walle, VasDolly, packer-ng, AndResGuard, Sentry, Firebase App
Distribution, Gradle Play Publisher) do not trigger either error; the
evidence is in [this review
reply](flutter#193693 (comment)).
4. **Deleted** the app-path `applicationVariants.configureEach` block
and `configureAbiVersionCodeOverride`, together with their two
`@Suppress("DEPRECATION")` markers and the unsafe `as ApkVariantOutput`
cast. The add-to-app module path (`addFlutterDepsForModule`,
`libraryVariants`) is left for PR 8.
5. **Structure follows the PR 6 review** (@mboetger's point that
`registerFlutterAssetTasks` should not register the compile task).
`onVariants` calls `configureSplitPerAbiVersionCodes` and
`registerCopyFlutterApksTask` after `registerFlutterAssetTasks`, under
the same `isApplicationProject && shouldCompileFlutterForVariant` gate.
Each helper does one job, and no helper takes a parameter only to pass
it on.
6. **Docs:**
- `Migrating-Flutter-Gradle-Plugin-to-AGP-public-API.md`: decision
record 4, the replacement map, and items 2 and 3 of "Features that must
break".
- `website-page-draft.md`: versionCode recipes that do not read
`output.versionCode`, and the rules for APK transforms.
- Links to the draft carry a TODO for
[flutter#193713](flutter#193713), which
tracks publishing it on docs.flutter.dev.
7. **Tests:**
- `CopyFlutterApksTaskTest` (new, 5 tests).
- `DslVersionCodesTest` (new, 5 tests).
- 8 new `FlutterPluginTest` cases: defaultConfig and flavor offsets, the
no-versionCode warning, no split, the force flag, copy wiring,
profile/custom build type naming, and assemble wiring. The mocked
`VariantOutput.versionCode` stubs only `set`, so any read fails the
test.
- `flutter_build_apk_split_per_abi_test.dart`: a fourth test builds with
`android.compatibility.enableLegacyApi=false`, and every test asserts
each per-ABI APK is in `flutter-apk`.
### Review response (commit `33f39876b92`)
| Comment | Change |
| --- | --- |
| Caching annotation: "How do I know this is true?" | Uses Gradle's own
`Copy`/`Sync` annotation and reason (checked with `javap`). |
| Why would `load` return null? / How would ABIs mismatch? | Comments
say exactly when each can happen. Errors point at the plugin that
transforms the APK. |
| Other places that build APK names | FGP has one. The tool's three
reading sites are listed in the reply (ratchet: not changed here). |
| Custom variants, and proof the copy works | Build-mode rule matches
the deleted code. Results of a flavor and custom build type scratch app
are in the reply. |
| Temporal wording | Removed from KDoc and docs. |
| Link to the website docs | TODO tied to flutter#193713 until the page is
published. |
| Reading `output.versionCode` depends on compatibility mode | No read.
`finalizeDsl` snapshot instead, with a compatibility-mode-off
integration test. |
| Why ×10000, and can the earlier numbers be kept? | Explained in the
replies. Keeping them requires reading the value the app set, which AGP
rejects with compatibility mode off. |
### Why removing the deleted code is safe
The deleted code used `AbstractAppExtension.applicationVariants`,
`ApkVariantOutput.versionCodeOverride`/`getFilter`, and
`packageApplicationProvider`. AGP deprecated these, and they are not
available with AGP 9's `android.newDsl=true`. The replacements
(`ApplicationVariant.outputs`, `VariantOutput.versionCode`/`filters`,
`SingleArtifact.APK`, `BuiltArtifactsLoader`,
`DslLifecycle.finalizeDsl`) are public `com.android.build.api` APIs
available at the stack's AGP 8.11.1 floor.
### Behavioral and compatibility notes
1. **versionCode for apps that transform it in their own `onVariants`
(breaking).** Flutter registers its `onVariants` callback when the
plugin is applied, so AGP runs it before an app's
`androidComponents.onVariants` block. `versionCodeOverride` was applied
after that block. Apps that set `versionCode` only in the `android {}`
DSL see no change. An app that multiplies by 10000 (compatibility mode
on), built with `--build-number 42`:
| ABI (offset) | `versionCodeOverride` | This PR |
| --- | --- | --- |
| `armeabi-v7a` (1) | 421000 | 10420000 |
| `arm64-v8a` (2) | 422000 | 20420000 |
| `x86_64` (4) | 424000 | 40420000 |
Values stay distinct, keep ABI order, and only go up, so Play upgrades
keep working. With compatibility mode off, apps can't read
`output.versionCode` either. For that case the docs give a recipe that
sets an absolute value in the app's `onVariants`, which replaces
Flutter's: `offset * 1000 + flutter.versionCode * 10000`.
2. **A versionCode declared only in the manifest is not offset.** The
DSL snapshot can't see it, so Flutter logs a warning and leaves the
variant's versionCodes unchanged.
3. **A `finalizeDsl` callback registered after Flutter's that changes
versionCode is not seen.** This is documented in the `DslVersionCodes`
KDoc and the migration doc.
4. **`copyFlutterApks<Variant>` tasks appear in `gradlew tasks`** and
can be UP-TO-DATE.
5. **Two build types that map to the same Flutter mode share a file
name.** For example, `debug` and a debuggable `staging` both write
`app-debug.apk`; the deleted code had the same clash. Running both
assembles in one `./gradlew` invocation makes the two copy tasks
alternate. The `flutter` tool builds one variant per invocation, so it
is unaffected.
### Integration test coverage of the changed paths
| Path | Tests |
| --- | --- |
| Per-ABI versionCode: default, build number, app `onVariants`
transform, compatibility mode off |
`flutter_build_apk_split_per_abi_test.dart` (4 tests; checks
versionCodes with `apkanalyzer` and the per-ABI files in `flutter-apk`)
|
| flutter-apk copy, default and flavored |
`android_gradle_asset_merging_test.dart`,
`gradle_libapp_so_packaging_test.dart` (incl. flavors),
`android_plugin_example_app_build_test.dart`,
`isolated/native_assets_flutter_build_test.dart`; devicelab
`flavors_test`, `gradle_desugar_classes_test` |
| Plugin unit tests on AGP 8.11.1 and AGP 9 |
`android_run_flutter_gradle_plugin_tests_test.dart` |
### Tests run locally
- `./gradlew test` in `packages/flutter_tools/gradle` (JDK 17): pass (33
suites, 0 failures).
- ktlint 1.5.0 with the CI `.editorconfig` and baseline: clean.
- `dart format` / `dart analyze --fatal-infos` on the changed Dart test:
clean.
- `flutter_build_apk_split_per_abi_test` on `33f39876b92`: 4/4 pass.
- On the review changes before the final edits to comments and error
messages: `android_gradle_asset_merging_test` (4),
`gradle_libapp_so_packaging_test` (4),
`android_run_flutter_gradle_plugin_tests_test` (2) all pass.
- Manual build with `enableLegacyApi=false` (AGP 9.3.1): versionCodes
1042/2042/4042. A negative control that re-adds the read fails with
"configuration of project ':app' has not completed yet".
- Scratch app with `free`/`paid` flavors and a custom `staging` build
type: APK names and versionCodes match the deleted code.
</details>
---
## 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 in-code documentation (doc comments with
`///`).
- [x] If this PR introduces a new feature or capability, I created and
linked a website documentation issue or PR in [flutter/website] (or
verified none is needed).
- [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.
<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[AI contribution guidelines]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[flutter/website]: https://github.com/flutter/website
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md1 parent 041e88f commit 8608bc9
12 files changed
Lines changed: 1014 additions & 121 deletions
File tree
- docs/platforms/android
- packages/flutter_tools
- gradle/src
- main/kotlin
- tasks
- test/kotlin
- tasks
- testing
- test/integration.shard
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
13 | 13 | | |
14 | 14 | | |
15 | 15 | | |
16 | | - | |
| 16 | + | |
| 17 | + | |
17 | 18 | | |
18 | 19 | | |
19 | 20 | | |
| |||
77 | 78 | | |
78 | 79 | | |
79 | 80 | | |
80 | | - | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
81 | 99 | | |
82 | 100 | | |
83 | 101 | | |
| |||
105 | 123 | | |
106 | 124 | | |
107 | 125 | | |
108 | | - | |
| 126 | + | |
109 | 127 | | |
110 | 128 | | |
111 | 129 | | |
| |||
165 | 183 | | |
166 | 184 | | |
167 | 185 | | |
168 | | - | |
169 | | - | |
170 | | - | |
171 | | - | |
172 | | - | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
173 | 232 | | |
174 | 233 | | |
175 | 234 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
81 | 81 | | |
82 | 82 | | |
83 | 83 | | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
84 | 98 | | |
85 | 99 | | |
86 | 100 | | |
| |||
96 | 110 | | |
97 | 111 | | |
98 | 112 | | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
99 | 152 | | |
100 | 153 | | |
101 | 154 | | |
102 | 155 | | |
103 | | - | |
104 | | - | |
| 156 | + | |
| 157 | + | |
105 | 158 | | |
106 | 159 | | |
107 | 160 | | |
108 | 161 | | |
109 | 162 | | |
110 | | - | |
111 | | - | |
112 | | - | |
113 | | - | |
114 | | - | |
115 | | - | |
| 163 | + | |
| 164 | + | |
116 | 165 | | |
117 | 166 | | |
118 | 167 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
0 commit comments