Migrate to the Android-KMP library plugin

Kotlin Multiplatform has a Gradle plugin to configure the library module.

The com.android.kotlin.multiplatform.library plugin is the official replacement for the previous method of adding Android targets to KMP libraries using the regular Android library Gradle plugin (com.android.library).

The previous approach is now deprecated in favor of the plugin, also referred to as the Android-KMP plugin. Continuing to use the com.android.library plugin for KMP will no longer be supported by JetBrains and won't benefit from future updates and improvements.

To migrate to this plugin, refer to the Apply the Android-KMP plugin section.

Key features and differences

The Android-KMP plugin is tailored specifically for KMP projects and differs from the standard com.android.library plugin in several key aspects:

  • Single variant architecture: The plugin uses a single variant, removing support for product flavors and build types, which simplifies configuration and enhances build performance.

  • Optimized for KMP: The plugin is designed for KMP libraries, focusing on shared Kotlin code and interoperability, omitting support for Android-specific native builds, AIDL, and RenderScript.

  • Tests disabled by default: Both unit and device (instrumentation) tests are disabled by default to enhance build speed. You can enable them if required.

  • No top-Level Android extension: Configuration is handled with an androidLibrary block within the Gradle KMP DSL, maintaining a consistent KMP project structure. There's no top-level android extension block.

  • Opt-in Java compilation: Java compilation is disabled by default. Use withJava() in the androidLibrary block to enable it. This improves build times when Java compilation is not needed.

Benefits of the Android-KMP library plugin

The Android-KMP plugin provides the following benefits for KMP projects:

  • Improved build performance and stability: It's engineered for optimized build speeds and enhanced stability within KMP projects. It's focus on KMP workflows contribute to a more efficient and reliable build process.

  • Enhanced IDE integration: It provides better code completion, navigation, debugging, and overall developer experience when working with KMP Android libraries.

  • Simplified project configuration: The plugin simplifies configuration for KMP projects by removing Android-specific complexities like build variants. This leads to cleaner and more maintainable build files. Previously, using the com.android.library plugin in KMP project could create confusing source set names, such as androidAndroidTest. This naming convention was less intuitive for developers familiar with standard KMP project structures.

Apply the Android-KMP plugin to an existing module

To apply the Android-KMP plugin to an existing KMP library module, follow these steps:

  1. Declare plugins in version catalog. Open the version catalog TOML file (usually gradle/libs.versions.toml) and add the plugin definitions section:

    # To check the version number of the latest Kotlin release, go to
# https://kotlinlang.org/docs/releases.html

[versions]
androidGradlePlugin = "8.12.0"
kotlin = "KOTLIN_VERSION"

[plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "androidGradlePlugin" }

  2. Apply the plugin declaration in root build file. Open the build.gradle.kts file located in the root directory of your project. Add the plugin aliases to the plugins block using apply false. This makes the plugin aliases available to all subprojects without applying the plugin logic to the root project itself.

    Kotlin

    // Root build.gradle.kts file

plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

    Groovy

    // Root build.gradle file

plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

  3. Apply the plugin in a KMP library module build file. Open the build.gradle.kts file in your KMP library module and apply the plugin at the top of your file within the plugins block:

    Kotlin

    // Module-specific build.gradle.kts file

plugins {
   alias(libs.plugins.kotlin.multiplatform)

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library)
}

    Groovy

    // Module-specific build.gradle file

plugins {
   alias(libs.plugins.kotlin.multiplatform)

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library)
}

  4. Configure Android KMP target. Configure the Kotlin Multiplatform block (kotlin) to define the Android target. Within the kotlin block, specify the Android target using androidLibrary:

    Kotlin

    kotlin {
   androidLibrary {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

       withJava() // enable java compilation support
       withHostTestBuilder {}.configure {}
       withDeviceTestBuilder {
           sourceSetTreeName = "test"
       }

       compilations.configureEach {
           compilerOptions.configure {
               jvmTarget.set(
                   org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
               )
           }
       }
   }

   sourceSets {
       androidMain {
           dependencies {
               // Add Android-specific dependencies here
           }
       }
       getByName("androidHostTest") {
           dependencies {
           }
       }

       getByName("androidDeviceTest") {
           dependencies {
           }
       }
   }
   // ... other targets (JVM, iOS, etc.) ...
}

    Groovy

    kotlin {
   androidLibrary {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

       withJava() // enable java compilation support
       withHostTestBuilder {}.configure {}
       withDeviceTestBuilder {
           it.sourceSetTreeName = "test"
       }

       compilations.configureEach {
           compilerOptions.options.jvmTarget.set(
               org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
           )
       }
   }

   sourceSets {
       androidMain {
           dependencies {
           }
       }
       androidHostTest {
           dependencies {
           }
       }
       androidDeviceTest {
           dependencies {
           }
       }
   }
   // ... other targets (JVM, iOS, etc.) ...
}

  5. Apply changes. After applying the plugin and configuring the kotlin block, sync your Gradle project to apply the changes.