Migrate to the Android-KMP plugin

Previously, the only way to integrate Android into a KMP project was to use the regular Android library Gradle plugin: com.android.library. However, this approach is now deprecated in favor of the dedicated com.android.kotlin.multiplatform.library plugin, also referred to as the Android-KMP plugin. This guide explains how to migrate to the new plugin.

Key features and differences

The Android-KMP plugin (com.android.kotlin.multiplatform.library) is tailored specifically for KMP projects and differs from the traditional com.android.library plugin in several key aspects:

  • Single variant architecture: The plugin operates with a single variant, streamlining the build process by removing support for product flavors and build types commonly found in standard Android library projects. This simplifies configuration and enhances build performance for KMP Android libraries.
  • Optimized for KMP: The plugin is specifically designed for Kotlin Multiplatform libraries, focusing on shared Kotlin code and interoperability. Consequently, it omits support for Android-specific native builds, AIDL (Android Interface Definition Language), and RenderScript, which are not typically relevant in a KMP shared code context.
  • Tests disabled by default: To further enhance build speed in a multiplatform environment, tests are disabled by default. You can explicitly enable tests if required for your project. This applies to both tests on host (unit tests) and tests on device (instrumentation tests).
  • No top-Level Android extension: The plugin doesn't create a top-level android extension in your Gradle build files. Configuration is handled with an androidLibrary block within the Kotlin multiplatform DSL, maintaining a consistent KMP project structure.
  • Opt-in Java compilation: Java compilation is not enabled by default. If your KMP library needs to compile Java-based code, you must explicitly opt in by using the withJava() API within the androidLibrary configuration block in your kotlin block. This allows for finer control over the compilation process and can improve build times when compilation of Java-based code is not required.

Benefits of migration

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

  • Improved build performance and stability: The Android-KMP plugin is engineered for optimized build speeds and enhanced stability within KMP projects. Its streamlined architecture and focus on KMP workflows contribute to a more efficient and reliable build process.
  • Enhanced IDE integration: The plugin provides superior integration with Android Studio and other Kotlin IDEs. This leads to better code completion, navigation, debugging, and overall developer experience when working with KMP Android libraries.
  • Simplified project configuration: By removing Android-specific complexities like variants, the Android-KMP plugin simplifies configuration for KMP projects. This results in cleaner, more maintainable build files and a reduced learning curve for developers new to KMP Android development. Previously, when integrating Android into a KMP project using the com.android.library plugin, the interplay between the Android Gradle plugin and the Kotlin Gradle plugin within the multiplatform structure sometimes resulted in misleading source set names. For instance, the source set dedicated to configuring Android instrumented tests was named androidAndroidTest. This naming convention was less intuitive for developers familiar with standard KMP project structures.
  • Official and recommended solution: The com.android.kotlin.multiplatform.library plugin is the official replacement for the previous method of adding Android targets to KMP libraries using the com.android.library plugin. Continuing to use the com.android.library plugin for KMP will no longer be supported by JetBrains and will not benefit from future updates and improvements.

Apply the Android-KMP plugin to a project

There are two primary ways to apply the Android-KMP plugin to your project: * For existing KMP library modules, edit your Gradle files manually. * For new KMP library modules, create the new module directly from the Android Studio UI.

Apply the plugin to an existing module

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

  1. Open your version catalog TOML file and add the following to the plugins section:

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

    Replace KOTLIN_PLUGIN_VERSION and ANDROID_KMP_PLUGIN_VERSION with the actual versions you're using.

  2. Open your build.gradle.kts (Kotlin) or build.gradle (Groovy) file in the root of your KMP library module.

  3. Apply the plugin at the top of your file within the plugins block:

    Kotlin

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

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

    Groovy

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

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

  4. 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. After applying the plugin and configuring the kotlin block, sync your Gradle project to apply the changes.

Create a new module with the plugin

You can also create a new Kotlin Multiplatform library module directly within Android Studio. This applies the necessary plugins automatically, including the Android-KMP plugin. For further guidance on how to create a new KMP library module with Android Studio, see Add Kotlin Multiplatform to an existing project.

For further information about the overall multiplatform ecosystem and more advanced configurations, see the official Kotlin Multiplatform documentation.