Files

TongTongStudio 1396487af9 refactor(page): 删除旧版页面文件

2026-08-16 05:31:45 +08:00

16 KiB

Raw Blame History

DSL Reference: AGP 8.x to AGP 9.x KMP Library Migration

Side-by-side mapping of every DSL element from the old com.android.library configuration to the new com.android.kotlin.multiplatform.library configuration.

Plugin IDs

Old (AGP 8.x)	New (AGP 9.x)
`com.android.library`	`com.android.kotlin.multiplatform.library`
`com.android.application`	`com.android.application` (unchanged, but cannot combine with KMP)
`org.jetbrains.kotlin.android`	Built into `com.android.application` and `com.android.library` in AGP 9.0 (do not apply separately)
`org.jetbrains.kotlin.kapt`	`com.android.legacy-kapt` (same version as AGP) or migrate to KSP
`org.jetbrains.kotlin.multiplatform`	`org.jetbrains.kotlin.multiplatform` (unchanged)

Top-Level Block Migration

Old	New
`android { ... }`	`kotlin { android { ... } }`
`androidTarget { ... }` (in kotlin block)	`android { ... }` (in kotlin block)

android {} Block Fields

Namespace and SDK Versions

Old (android {})	New (kotlin { android {} })
`namespace = "..."`	`namespace = "..."`
`compileSdk = 35`	`compileSdk = 35` (same value, just moved into `kotlin { android {} }`)
`defaultConfig { minSdk = 24 }`	`minSdk = 24`
`defaultConfig { targetSdk = 34 }`	N/A (application-only, not in library)

defaultConfig Elements

Old (android { defaultConfig {} })	New (kotlin { android {} })
`minSdk = 24`	`minSdk = 24` (direct property)
`testInstrumentationRunner = "..."`	Set in `withDeviceTest { }` configuration
`consumerProguardFiles("...")`	`consumerProguardFiles.add(file("..."))`
`multiDexEnabled = true`	N/A (handled automatically)
`vectorDrawables.useSupportLibrary = true`	N/A
`buildConfigField(...)`	Removed (see KNOWN-ISSUES.md)
`manifestPlaceholders[...]`	N/A (use merged manifest in app module)

Compile Options and Compiler Options

Old	New
`android { compileOptions { sourceCompatibility = JavaVersion.VERSION_11 } }`	`kotlin { android { compilerOptions { jvmTarget.set(JvmTarget.JVM_11) } } }`
`android { compileOptions { targetCompatibility = JavaVersion.VERSION_11 } }`	`kotlin { android { compilerOptions { jvmTarget.set(JvmTarget.JVM_11) } } }`
`kotlinOptions { jvmTarget = "11" }`	`compilerOptions { jvmTarget.set(JvmTarget.JVM_11) }`
`kotlinOptions { freeCompilerArgs += listOf("-Xopt-in=...") }`	`compilerOptions { optIn.add("...") }`
`kotlinOptions { languageVersion = "1.9" }`	`compilerOptions { languageVersion.set(KotlinVersion.KOTLIN_2_0) }`

Full JvmTarget import:

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

Build Features

Old (android { buildFeatures {} })	New (kotlin { android {} })
`buildFeatures { compose = true }`	Applied via compose compiler plugin (no explicit flag needed in KMP library)
`buildFeatures { buildConfig = true }`	Removed in KMP library (see KNOWN-ISSUES.md)
`buildFeatures { viewBinding = true }`	Not supported in KMP library
`buildFeatures { dataBinding = true }`	Not supported in KMP library
`buildFeatures { aidl = true }`	Not supported in KMP library
`buildFeatures { renderScript = true }`	Not supported
`buildFeatures { resValues = true }`	Not supported in KMP library

Android Resources

Old	New
Resources processed by default	Must explicitly enable
`android { ... }` (resources auto-included)	`kotlin { android { androidResources { enable = true } } }`

Test Options

Old	New
`android { testOptions { unitTests.isReturnDefaultValues = true } }`	`kotlin { android { withHostTest { } } }`
`android { testOptions { animationsDisabled = true } }`	`kotlin { android { withDeviceTest { } } }`
Source set: `androidUnitTest`	Source set: `androidHostTest` (alias: `androidUnitTest` still works)
Source set: `androidInstrumentedTest`	Source set: `androidDeviceTest` (alias: `androidInstrumentedTest` still works)
`testImplementation(...)`	`getByName("androidHostTest").dependencies { implementation(...) }`
`androidTestImplementation(...)`	`getByName("androidDeviceTest").dependencies { implementation(...) }`
Source dir: `src/test/`	Source dir: `src/androidHostTest/kotlin/`
Source dir: `src/androidTest/`	Source dir: `src/androidDeviceTest/kotlin/`

Test Configuration Details

// Old
android {
    testOptions {
        unitTests {
            isReturnDefaultValues = true
            isIncludeAndroidResources = true
        }
    }
}

// New
kotlin {
    android {
        withHostTest {
            // Host test specific configuration
            // returnDefaultValues and includeAndroidResources
            // are configured via gradle.properties or test runner
        }
        withDeviceTest {
            // Device test specific configuration
            instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
        }
    }
}

Lint Configuration

Old	New
`android { lint { abortOnError = false } }`	`kotlin { android { lint { abortOnError = false } } }`
`android { lint { checkReleaseBuilds = true } }`	`kotlin { android { lint { checkReleaseBuilds = true } } }`
`android { lint { disable += "SomeCheck" } }`	`kotlin { android { lint { disable += "SomeCheck" } } }`
`android { lint { baseline = file("lint-baseline.xml") } }`	`kotlin { android { lint { baseline = file("lint-baseline.xml") } } }`

The lint DSL is largely unchanged, it just moves inside kotlin { android {} }.

Note: useK2Uast is deprecated. Remove it if present.

Packaging / Resources Excludes

Old	New
`android { packaging { resources { excludes += "/META-INF/{AL2.0,LGPL2.1}" } } }`	`kotlin { android { packaging { resources { excludes += "/META-INF/{AL2.0,LGPL2.1}" } } } }`

The DSL is the same, just nested under kotlin { android {} }.

Syntax note for AGP 9.0:

// Old syntax (still works but deprecated)
resources.excludes += "/META-INF/{AL2.0,LGPL2.1}"

// Preferred AGP 9.0 syntax
resources {
    excludes.add("/META-INF/AL2.0")
    excludes.add("/META-INF/LGPL2.1")
}

Dependencies Configurations

Old Configuration	New Configuration	Notes
`implementation(...)`	`androidMain.dependencies { implementation(...) }`	Move to source set
`api(...)`	`androidMain.dependencies { api(...) }`	Move to source set
`compileOnly(...)`	`androidMain.dependencies { compileOnly(...) }`	Move to source set
`debugImplementation(...)`	`"androidRuntimeClasspath"(...)`	No variant-specific configs
`releaseImplementation(...)`	`androidMain.dependencies { implementation(...) }`	Single variant
`testImplementation(...)`	`getByName("androidHostTest").dependencies { implementation(...) }`
`androidTestImplementation(...)`	`getByName("androidDeviceTest").dependencies { implementation(...) }`
`ksp(...)`	`add("ksp", ...)` or KSP Gradle plugin DSL	Check KSP compatibility
`kapt(...)`	Migrate to KSP; kapt not supported

Dependency Resolution

Because the new KMP Android library plugin is strictly single-variant, you can no longer define fallback logic inside buildTypes or defaultConfig.

Old	New	Notes
`android { defaultConfig { missingDimensionStrategy("tier", "free") } }`	`kotlin { android { localDependencySelection { productFlavorDimension("tier") { selectFrom.set(listOf("free")) } } } }`	Configure dependency flavor fallbacks
`android { buildTypes { getByName("debug") { matchingFallbacks.add("release") } } }`	`kotlin { android { localDependencySelection { selectBuildTypeFrom.set(listOf("debug", "release")) } } }`	Configure dependency build type mapping

Build Types and Product Flavors

Removed in KMP library plugin. The com.android.kotlin.multiplatform.library plugin produces a single build variant.

Old	New	Notes
`buildTypes { debug { ... } }`	Removed	Single variant only
`buildTypes { release { minifyEnabled = true } }`	Removed	Minification is app-module concern
`productFlavors { ... }`	Removed	Use Gradle properties or expect/actual for variants
`flavorDimensions(...)`	Removed

Workarounds for Variant-Dependent Logic

Compile-time constants: Use expect/actual or dependency injection instead of BuildConfig.
Environment-specific behavior: Use Gradle properties or runtime configuration.
Different dependencies per build type: Not possible in KMP library. Move to app module.
Minification/ProGuard: Only relevant in the application module.

androidComponents Block

Old	New
`androidComponents { onVariants { ... } }`	Limited support; most variant API is unavailable
`androidComponents { beforeVariants { ... } }`	Not available in KMP library
`androidComponents { finalizeDsl { ... } }`	Not available in KMP library

The androidComponents extension is significantly reduced in scope for KMP libraries because there is only a single variant. Most customization that relied on variant-aware APIs must be reworked.

Note: android.enableLegacyVariantApi is removed in AGP 9.0 and will cause an error if set. Code depending on legacy variant APIs must be migrated to androidComponents APIs.

Java Source Compilation

Old	New
Java sources in `src/main/java/` compiled automatically	Must call `withJava()`
`android { compileOptions { ... } }`	`kotlin { android { withJava() } }`

kotlin {
    android {
        withJava()  // Required to compile .java files in androidMain
    }
}

Quick Reference: Minimal Migration Template

// OLD
plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.androidLibrary)
}
kotlin {
    androidTarget { compilations.all { kotlinOptions { jvmTarget = "11" } } }
}
android {
    namespace = "com.example.lib"
    compileSdk = 35
    defaultConfig { minSdk = 24 }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}

// NEW
plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.androidKmpLibrary)
}
kotlin {
    android {
        namespace = "com.example.lib"
        compileSdk = 35
        minSdk = 24
        compilerOptions {
            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
        }
    }
}

16 KiB Raw Blame History