Kotlin Tooling Agp9 Migration

KMP AGP 9.0 Migration

Android Gradle Plugin 9.0 makes the Android application and library plugins incompatible with the Kotlin Multiplatform plugin in the same module. This skill guides you through the migration.

Step 0: Analyze the Project

Before making any changes, understand the project structure:

1. Read settings.gradle.kts (or .gradle) to find all modules
2. For each module, read its build.gradle.kts to identify which plugins are applied
3. Check if the project uses a Gradle version catalog (gradle/libs.versions.toml). If it exists, read it for current AGP/Gradle/Kotlin versions. If not, find versions directly in build.gradle.kts files (typically in the root buildscript {} or plugins {} block). Adapt all examples in this guide accordingly — version catalog examples use alias(libs.plugins.xxx) while direct usage uses id("plugin.id") version "x.y.z"
4. Read gradle/wrapper/gradle-wrapper.properties for the Gradle version
5. Check gradle.properties for any existing workarounds (android.enableLegacyVariantApi)
6. Check for org.jetbrains.kotlin.android plugin usage — AGP 9.0 has built-in Kotlin and this plugin must be removed
7. Check for org.jetbrains.kotlin.kapt plugin usage — incompatible with built-in Kotlin, must migrate to KSP or com.android.legacy-kapt
8. Check for third-party plugins that may be incompatible with AGP 9.0 (see "Plugin Compatibility" section below)

If Bash is available, run scripts/analyze-project.sh from this skill's directory to get a structured summary.

Classify Each Module

For each module, determine its type:

Determine Scope

• Path B is mandatory for any module combining KMP + Android application plugin
• Path C is recommended when the project has a monolithic composeApp (or similar) module containing entry points for multiple platforms (Android, Desktop, Web). This aligns with the new JetBrains default project structure where each platform gets its own app module.
• Ask the user whether they want Path B only (minimum required) or Path C (recommended full restructure)

Path A: Library Module Migration

Use this when a module applies kotlin.multiplatform + com.android.library.

See references/MIGRATION-LIBRARY.md for full before/after code.

Summary:

1. Replace plugin: com.android.library → com.android.kotlin.multiplatform.library
2. Remove `org.jetbrains.kotlin.android` plugin if present (AGP 9.0 has built-in Kotlin support)
3. Migrate DSL: Move config from top-level android {} block into kotlin { android {} }: ``kotlin kotlin { android { namespace = "com.example.lib" compileSdk = 35 minSdk = 24 } } ``
4. Rename source directories (only if the module uses classic Android layout instead of KMP layout):

• src/main → src/androidMain
• src/test → src/androidHostTest
• src/androidTest → src/androidDeviceTest
• If the module already uses src/androidMain/, no directory renames are needed

1. Move dependencies from top-level dependencies {} into sourceSets: ``kotlin kotlin { sourceSets { androidMain.dependencies { implementation("androidx.appcompat:appcompat:1.7.0") } } } ``
2. Enable resources explicitly if the module uses Android or Compose Multiplatform resources: ``kotlin kotlin { android { androidResources { enable = true } } } ``
3. Enable Java compilation if module has .java source files: ``kotlin kotlin { android { withJava() } } ``
4. Enable tests explicitly if the module has unit or instrumented tests: ``kotlin kotlin { android { withHostTest { isIncludeAndroidResources = true } withDeviceTest { instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" } } } ``
5. Update Compose tooling dependency: ``kotlin // Old: debugImplementation(libs.androidx.compose.ui.tooling) // New: androidRuntimeClasspath(libs.androidx.compose.ui.tooling) ``
6. Publish consumer ProGuard rules explicitly if applicable: ``kotlin kotlin { android { consumerProguardFiles.add(file("consumer-rules.pro")) } } ``
7. Resolve Sub-dependency Variants (Product Flavors / Build Types): Because the new KMP Android library plugin enforces a single-variant architecture, it does not natively understand how to resolve dependencies that publish multiple variants (like debug/release build types, or product flavors like free/paid). Configure fallback behaviors using localDependencySelection: ```kotlin kotlin { android { localDependencySelection { // Determine which build type to consume from Android library dependencies, in order of preference selectBuildTypeFrom.set(listOf("debug", "release"))

// If the dependency has a 'tier' dimension, select the 'free' flavor productFlavorDimension("tier") { selectFrom.set(listOf("free")) } } } }

## Path B: Android App + Shared Module Split

Use this when a module applies `kotlin.multiplatform` + `com.android.application`. This is **mandatory** for AGP 9.0 compatibility.

See [references/MIGRATION-APP-SPLIT.md](references/MIGRATION-APP-SPLIT.md) for full guide.

Summary:

1. **Create `androidApp` module** with its own `build.gradle.kts`:

plugins { alias(libs.plugins.androidApplication) // Do NOT apply kotlin-android — AGP 9.0 includes Kotlin support alias(libs.plugins.composeMultiplatform) // if using Compose alias(libs.plugins.composeCompiler) // if using Compose }

android { namespace = "com.example.app" compileSdk = 35 defaultConfig { applicationId = "com.example.app" minSdk = 24 targetSdk = 35 versionCode = 1 versionName = "1.0" } buildFeatures { compose = true } }

dependencies { implementation(projects.shared) // or whatever the shared module is named implementation(libs.androidx.activity.compose) }

2. **Move Android entry point code** from `src/androidMain/` to `androidApp/src/main/`:
   - `MainActivity.kt` (and any other Activities/Fragments)
   - `AndroidManifest.xml` (app-level manifest with `<application>` and launcher `<activity>`) — verify `android:name` on `<activity>` uses the fully qualified class name in its new location
   - Android Application class if present
   - App-level resources (launcher icons, theme, etc.)
3. **Add to `settings.gradle.kts`**: `include(":androidApp")`
4. **Add to root `build.gradle.kts`**: plugin declarations with `apply false`
5. **Convert original module** from application to library using Path A steps
6. **Ensure different namespaces**: app module and library module must have distinct namespaces