mikkeli
557b2d92a5
`flutter create --platforms android` output, unmodified except for docs and one
commented-out escape hatch. The generated toolchain is already what we want --
Gradle 9.3.1 / AGP 9.1.0 / Kotlin 2.4.0 / Java 17 -- because Flutter's template
defaults ARE the policy: they sit above the warn floor, where the floors-only
combo sits one release from breaking.
The point of this repo is the notes, not the code. README.md records why two
apps in this org stopped building without their code changing, where Flutter
keeps its version floors (read them, do not recall them), and four traps that
appear in no changelog: the pub-cache edit that hides from git, kotlinOptions{}
being a compilation error rather than a deprecation under Kotlin >= 2.3, AGP 8.x
being unable to run on Gradle >= 9.6, and Built-in Kotlin being a dead end while
AGP ships a Kotlin below Flutter's own floor.
android/build.gradle.kts carries a commented-out subprojects{} override for
abandoned pub plugins whose declared compileSdk their own AndroidX dependencies
now reject. Off by default: turn it on when a build fails, not speculatively.
Verified: flutter build apk --debug and --release against Flutter 3.47.1.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016dKAqFo9Uj3mPZWvDzj3G8
29 lines
1.6 KiB
Markdown
29 lines
1.6 KiB
Markdown
---
|
|
desc: build-toolchain rules for Flutter Android apps in this org
|
|
---
|
|
|
|
# Working on this project
|
|
|
|
Read [README.md](README.md) before touching anything under `android/`. It is short, and it
|
|
is the accumulated cost of two apps that stopped building without their code changing.
|
|
|
|
The four rules that matter, in the order they get violated:
|
|
|
|
1. **Never edit `~/.pub-cache`.** Shared between users, unversioned, invisible to git, wiped
|
|
by the next `pub get`. If a plugin needs different build settings, override them from
|
|
`android/build.gradle.kts` (worked example inside, commented out). To undo damage:
|
|
`dart pub cache repair --all`.
|
|
2. **Do not guess version numbers.** Flutter's Gradle/AGP/Kotlin/Java floors live in
|
|
`$FLUTTER_ROOT/packages/flutter_tools/gradle/src/main/kotlin/DependencyVersionChecker.kt`
|
|
and `.../lib/src/android/gradle_utils.dart`. Read them. `flutter-android-preflight` does
|
|
it for you and `--fix` applies the result.
|
|
3. **Run `flutter-android-preflight .` before debugging a build failure**, and after every
|
|
`flutter upgrade`. Most "Gradle is broken" symptoms are one of its checks.
|
|
4. **Do not migrate to Built-in Kotlin yet**, however loudly Flutter warns. On Flutter
|
|
3.47.1 the migration is self-contradictory — AGP 9.1.0 supplies Kotlin 2.2.10, below
|
|
Flutter's own 2.2.20 floor. Keep `android.builtInKotlin=false`.
|
|
|
|
When a build fails, read the error before changing versions. Climbing the Gradle version
|
|
ladder one release at a time produces a different, equally confusing error at each rung and
|
|
converges on nothing — the floors are all knowable up front, from the two files above.
|