Android Gradle and AGP

This topic focuses on Android Gradle Plugin and build-system engineering.

Android Gradle problems are rarely solved by reading one concept article. Teams usually need to fix slow builds, failed AGP upgrades, KSP/Kotlin version conflicts, unstable CI, and messy module dependencies. This page reorganizes the build-system notes around AGP 9 migration and build governance.

The goal is to make build speed and build reliability measurable engineering concerns.

Migration Checklist

1. Freeze the version matrix for Gradle, AGP, Kotlin, KSP, JDK, and Android Studio.
2. Use Build Scan or structured build logs to determine whether time is spent in configuration, task execution, KSP/KAPT, resource processing, or R8.
3. Enable Configuration Cache compatibility checks module by module instead of changing the whole repository at once.
4. Move dependency versions into Version Catalog and move repeated build logic into Convention Plugins.
5. Add CI gates for build duration, cache hit rate, lint, unit tests, and artifact verification.

AGP 9 Concerns

• Built-in Kotlin: AGP 9 enables built-in Kotlin support by default, so upgrades must handle the relationship between Kotlin Gradle Plugin and KSP versions.
• Default behavior changes: build features, R8, NDK behavior, and compileSdk consumer constraints can affect older projects.
• Test fixtures and IDE support: migration has to validate Android Studio behavior, not just command-line builds.
• Plugin compatibility: custom Gradle plugins, bytecode instrumentation, resource processing, and publishing plugins need separate verification.

Core Reading

• Mobile Engineering
• How to analyze slow Android Gradle builds: from configuration time to task execution
• Android Gradle build optimization: Configuration Cache, KSP, and task governance
• Android Gradle Version Catalog and Convention Plugins
• Android APK build pipeline: aapt2, V4 signatures, and AGP internals
• What should Android CI/CD quality gates include?

Debugging Route

• Slow builds: start with configuration time and remote cache hit rate, then inspect task hot spots.
• Slow Kotlin/KSP: inspect processor count, incremental support, module boundaries, and generated-code volume.
• Slow R8: inspect keep rules, resource shrinking, input size, and multi-variant build behavior.
• Slow CI: inspect cache directories, dependency downloads, concurrency strategy, test layering, and artifact reuse.
• Failed upgrades: reduce the problem to the smallest module first, then reintroduce plugins and custom tasks one by one.

Official References

• Android Gradle plugin release notes
• AGP 9.0 release notes
• Migrate to built-in Kotlin

Related Topics

• Kotlin and Coroutines: Kotlin, KSP, K2, and compiler changes directly affect the Android build pipeline.
• Android Performance: performance gates should connect Macrobenchmark, startup time, and production metrics into CI.