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.
|