Menyiapkan plugin library Android Gradle untuk KMP

Plugin Gradle com.android.kotlin.multiplatform.library adalah alat yang didukung secara resmi untuk menambahkan target Android ke modul library Kotlin Multiplatform (KMP). Plugin ini menyederhanakan konfigurasi project, meningkatkan performa build, dan menawarkan integrasi yang lebih baik dengan Android Studio.

Penggunaan plugin com.android.library untuk pengembangan KMP bergantung pada API Plugin Android Gradle yang tidak digunakan lagi dan memerlukan keikutsertaan di plugin Android Gradle 9.0 dan yang lebih tinggi (Q4 2025). API ini diperkirakan akan dihapus di plugin Android Gradle 10.0 (paruh kedua tahun 2026).

Untuk menerapkan plugin ini, lihat bagian Menerapkan plugin Android-KMP. Jika Anda perlu bermigrasi dari API lama, lihat Panduan Migrasi.

Untuk mendapatkan bantuan terkait migrasi AGP 9.0+, Anda dapat menggunakan kemampuan agen yang dibuat oleh JetBrains untuk aplikasi KMP. Untuk mengetahui informasi selengkapnya tentang cara menggunakan keterampilan di Android Studio, lihat Memperluas Mode Agen dengan keterampilan. Perlu diingat bahwa hasil AI tidak sepenuhnya dapat diprediksi.

Fitur dan perbedaan utama

Plugin Android-KMP disesuaikan secara khusus untuk project KMP dan berbeda dari plugin com.android.library standar dalam beberapa aspek utama:

• Arsitektur varian tunggal: Plugin menggunakan varian tunggal, sehingga menghapus dukungan untuk ragam produk dan jenis build, yang menyederhanakan konfigurasi dan meningkatkan performa build.

• Dioptimalkan untuk KMP: Plugin ini dirancang untuk library KMP, dengan fokus pada kode Kotlin bersama dan interoperabilitas, serta menghilangkan dukungan untuk build native khusus Android, AIDL, dan RenderScript.

• Pengujian dinonaktifkan secara default: Pengujian unit dan perangkat (instrumentasi) dinonaktifkan secara default untuk meningkatkan kecepatan build. Anda dapat mengaktifkannya jika diperlukan.

• Tidak ada ekstensi Android level teratas: Konfigurasi ditangani dengan blok android dalam DSL KMP Gradle, sehingga mempertahankan struktur project KMP yang konsisten. Tidak ada blok ekstensi android tingkat teratas.

• Keikutsertaan kompilasi Java: Kompilasi Java dinonaktifkan secara default. Gunakan withJava() di blok android untuk mengaktifkannya. Hal ini akan meningkatkan waktu build saat kompilasi Java tidak diperlukan.

Manfaat plugin library Android-KMP

Plugin Android-KMP memberikan manfaat berikut untuk project KMP:

• Peningkatan performa dan stabilitas build: Library ini dirancang untuk kecepatan build yang dioptimalkan dan stabilitas yang ditingkatkan dalam project KMP. Fokusnya pada alur kerja KMP berkontribusi pada proses build yang lebih efisien dan andal.

• Integrasi IDE yang ditingkatkan: Library ini memberikan pelengkapan kode, navigasi, proses debug, dan pengalaman developer yang lebih baik secara keseluruhan saat menggunakan library Android KMP.

• Konfigurasi project yang disederhanakan: Plugin ini menyederhanakan konfigurasi untuk project KMP dengan menghapus kompleksitas khusus Android seperti varian build. Hal ini menghasilkan file build yang lebih rapi dan mudah dikelola. Sebelumnya, penggunaan plugin com.android.library dalam project KMP dapat membuat nama set sumber yang membingungkan, seperti androidAndroidTest. Konvensi penamaan ini kurang intuitif bagi developer yang sudah memahami struktur project KMP standar.

Solusi untuk fitur yang tidak didukung

Jika dibandingkan dengan integrasi KMP dengan plugin com.android.library, beberapa fitur tidak ada di plugin com.android.kotlin.multiplatform.library. Berikut adalah solusi untuk fitur yang tidak didukung:

• Varian build

  Jenis build dan ragam produk tidak didukung. Hal ini karena plugin baru menggunakan arsitektur varian tunggal, yang menyederhanakan konfigurasi dan meningkatkan performa build.

  Jika Anda memerlukan varian build, sebaiknya buat modul library Android mandiri terpisah menggunakan plugin com.android.library, konfigurasikan jenis build dan ragam produk dalam modul tersebut, lalu gunakan sebagai dependensi project standar dari set sumber androidMain library Kotlin Multiplatform Anda. Untuk mengetahui detail selengkapnya, lihat Membuat library Android dan Mengonfigurasi varian build.

• Data binding dan View binding

  Fitur ini adalah fitur framework UI khusus Android yang terkait erat dengan sistem View Android dan tata letak XML. Dengan plugin library Android-KMP yang baru, sebaiknya Anda menangani UI menggunakan framework multiplatform seperti Compose Multiplatform. Data binding dan View binding dianggap sebagai detail implementasi aplikasi Android final, bukan library yang dapat dibagikan.

• Dukungan build native

  Plugin baru ini berfokus pada pembuatan AAR standar untuk target Android. Integrasi kode native di Multiplatform Kotlin ditangani langsung oleh target native KMP sendiri (seperti androidNativeArm64 dan androidNativeX86) dan kemampuan interop C-nya. Jika perlu menyertakan kode C/C++ native, Anda harus menentukannya sebagai bagian dari set sumber umum atau native dan mengonfigurasi interop C dalam blok kotlin, bukan menggunakan mekanisme externalNativeBuild khusus Android.

  Atau, jika Anda memerlukan dukungan build native melalui externalNativeBuild, sebaiknya buat modul com.android.library mandiri terpisah tempat Anda dapat mengintegrasikan kode native, dan gunakan library mandiri tersebut dari set sumber androidMain project library Kotlin Multiplatform Anda. Untuk mengetahui detail selengkapnya, lihat Membuat library Android dan Menambahkan kode C dan C++ ke project Anda.

• Class BuildConfig

  Fitur BuildConfig paling berguna di lingkungan multi-varian. Karena plugin library Multiplatform Kotlin yang baru bersifat agnostik varian dan tidak mendukung jenis build dan ragam produk, fitur ini tidak diimplementasikan. Sebagai alternatif, sebaiknya gunakan plugin BuildKonfig atau solusi komunitas serupa untuk membuat metadata bagi semua target.

Prasyarat

Untuk menggunakan plugin com.android.kotlin.multiplatform.library, project Anda harus dikonfigurasi dengan versi minimum berikut atau yang lebih tinggi:

• Plugin Android Gradle (AGP): 8.10.0
• Kotlin Gradle Plugin (KGP): 2.0.0

Menerapkan plugin Android-KMP ke modul yang ada

Untuk menerapkan plugin Android-KMP ke modul library KMP yang ada, ikuti langkah-langkah berikut:

1. Mendeklarasikan plugin di katalog versi. Buka file TOML katalog versi (biasanya gradle/libs.versions.toml) dan tambahkan bagian definisi plugin:

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "9.4.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. Terapkan deklarasi plugin di file build root. Buka file build.gradle.kts yang terletak di direktori utama project Anda. Tambahkan alias plugin ke blok plugins menggunakan apply false. Hal ini membuat alias plugin tersedia untuk semua subproject tanpa menerapkan logika plugin ke project root itu sendiri.

   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. Terapkan plugin dalam file build modul library KMP. Buka file build.gradle.kts di modul library KMP dan terapkan plugin di bagian atas file dalam blok plugins:

   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. Konfigurasikan target KMP Android. Konfigurasikan blok Multiplatform Kotlin (kotlin) untuk menentukan target Android. Dalam blok kotlin, tentukan target Android menggunakan android:

   Kotlin

   kotlin {
      android {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              sourceSetTreeName = "test"
          }
   
          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 {
      android {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              it.sourceSetTreeName = "test"
          }
   
          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. Terapkan perubahan. Setelah menerapkan plugin dan mengonfigurasi blok kotlin, sinkronkan project Gradle Anda untuk menerapkan perubahan.

Bermigrasi dari plugin lama

Panduan ini membantu Anda bermigrasi dari plugin com.android.library lama ke plugin com.android.kotlin.multiplatform.library.

1. Memindahkan sumber

Plugin lama memungkinkan Anda menggunakan set sumber src/main, src/test, dan src/androidTest, selain src/androidMain, src/androidHostTest, dan src/androidDeviceTest. Plugin baru hanya menggunakan direktori sumber yang terakhir, jadi Anda harus memindahkan sumber dari src/main ke src/androidMain, dari src/test ke src/androidHostTest, dan dari src/androidTest ke src/androidDeviceTest.

2. Mengonfigurasi direktori resource dan sumber kustom

Jika Anda memiliki sumber atau resource di direktori non-standar, Anda sebelumnya mengonfigurasinya menggunakan blok sourceSets. Dengan plugin baru, gunakan ekstensi androidComponents untuk menambahkan direktori sumber statis ke varian.

Perhatikan bahwa dengan plugin baru, metode addStaticSourceDirectory menambahkan direktori ke daftar direktori sumber yang ada. Dengan plugin lama, metode setSrcDirs mengganti daftar, sedangkan metode srcDir menambahkannya.

// build.gradle.kts

androidComponents {
    onVariants { variant ->
        // Add a directory for Kotlin sources
        variant.sources.kotlin?.addStaticSourceDirectory("other/kotlin")

        // Add a directory for Android assets
        variant.sources.assets?.addStaticSourceDirectory("other/assets")
    }
}

// build.gradle.kts

android {
    sourceSets {
        getByName("main") {
            // Replaces the directory for Kotlin sources.
            kotlin.setSrcDirs(listOf("other/kotlin"))

            // Appends a directory for assets.
            assets.srcDir("other/assets")
        }
    }
}

3. Mendeklarasikan dependensi

Tugas umum adalah mendeklarasikan dependensi untuk set sumber khusus Android. Plugin baru mengharuskan dependensi ini ditempatkan secara eksplisit dalam blok sourceSets, tidak seperti blok dependencies umum yang digunakan sebelumnya.

// build.gradle.kts

kotlin {
    android {}
    //... other targets

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
        }

        // Dependencies are now scoped to the specific Android source set
        androidMain.dependencies {
            implementation("androidx.appcompat:appcompat:1.7.0")
            implementation("com.google.android.material:material:1.11.0")
        }
    }
}

// build.gradle.kts

kotlin {
    android {
        compilations.getByName("deviceTest") {
            kotlinOptions.languageVersion = "2.0"
        }
    }
}

// build.gradle.kts

kotlin {
  androidTarget()
  //... other targets
}

// Dependencies for all source sets were often mixed in one block
dependencies {
  // Common dependencies
  commonMainImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")

  // Android-specific dependencies
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("com.google.android.material:material:1.11.0")
}

4. Mengaktifkan resource Android

Dukungan untuk Resource Android (folder res) tidak diaktifkan secara default dengan plugin baru untuk mengoptimalkan performa build. Anda harus mengaktifkan fitur ini agar dapat menggunakannya. Perubahan ini membantu memastikan bahwa project yang tidak memerlukan resource khusus Android tidak terbebani oleh overhead build terkait.

// build.gradle.kts

kotlin {
  android {
    // ...
    // Enable Android resource processing
    androidResources {
      enable = true
    }
  }
}

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

// build.gradle.kts

android {
    namespace = "com.example.library"
    compileSdk = 34
    // No extra configuration was needed to enable resources.
}

// Project Structure
// └── src
//     └── main
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

5. Mengonfigurasi pengujian host dan perangkat

Secara default, plugin baru menonaktifkan pengujian sisi host (unit) dan sisi perangkat (berinstrumen) Android. Anda harus secara eksplisit memilih ikut serta untuk membuat konfigurasi dan set sumber pengujian, sedangkan plugin lama membuatnya secara otomatis.

Model keikutsertaan ini membantu memastikan bahwa project Anda tetap ramping dan hanya menyertakan logika build dan set sumber yang Anda gunakan secara aktif.

// build.gradle.kts

kotlin {
  android {
    // ...

    // Opt-in to enable and configure host-side (unit) tests
    withHostTest {
      isIncludeAndroidResources = true
    }

    // Opt-in to enable and configure device-side (instrumented) tests
    withDeviceTest {
      instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
      execution = "HOST"
    }
  }
}

// Project Structure (After Opt-in)
// └── src
//     ├── androidHostTest
//     └── androidDeviceTest

// build.gradle.kts

android {
  defaultConfig {
    // Runner was configured in defaultConfig
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
  }

  testOptions {
    // Configure unit tests (for the 'test' source set)
    unitTests.isIncludeAndroidResources = true

    // Configure device tests (for the 'androidTest' source set)
    execution = "HOST"
  }
}

// Project Structure (Defaults)
// └── src
//     ├── test
//     └── androidTest

6. Mengaktifkan kompilasi sumber Java

Jika library KMP Anda perlu mengompilasi sumber Java untuk target Android-nya, Anda harus mengaktifkan fungsi ini secara eksplisit dengan plugin baru. Perhatikan bahwa tindakan ini memungkinkan kompilasi untuk file Java yang terletak langsung di dalam project Anda, bukan untuk dependensinya. Metode untuk menetapkan versi target JVM compiler Java dan Kotlin juga berubah.

// build.gradle.kts

kotlin {
  android {
    //  Opt-in to enable Java source compilation
    withJava()
    // Configure the JVM target for both Kotlin and Java sources
    compilerOptions {
      jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
    }
  }
  // ...
}

// Project Structure:
// └── src
//     └── androidMain
//         ├── kotlin
//         │   └── com/example/MyKotlinClass.kt
//         └── java
//             └── com.example/MyJavaClass.java

// build.gradle.kts

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

kotlin {
  androidTarget {
    compilations.all {
      kotlinOptions.jvmTarget = "1.8"
    }
  }
}

7. Berinteraksi dengan varian build menggunakan androidComponents

Ekstensi androidComponents masih tersedia untuk berinteraksi dengan artefak build secara terprogram. Meskipun sebagian besar Variant API tetap sama, antarmuka AndroidKotlinMultiplatformVariant baru lebih terbatas karena plugin hanya menghasilkan satu varian.

Oleh karena itu, properti yang terkait dengan jenis build dan ragam produk tidak lagi tersedia di objek varian.

// build.gradle.kts

androidComponents {
  onVariants { variant ->
      val artifacts = variant.artifacts
  }
}

// build.gradle.kts

androidComponents {
  onVariants(selector().withBuildType("release")) { variant ->
    // ...
  }
}

8. Memilih varian dependensi library Android

Library KMP Anda menghasilkan satu varian untuk Android. Namun, Anda mungkin bergantung pada library Android standar (com.android.library) yang memiliki beberapa varian (misalnya, ragam produk free/paid). Mengontrol cara project Anda memilih varian dari dependensi tersebut adalah persyaratan umum.

// build.gradle.kts
kotlin {
  android {
    localDependencySelection {
      // For dependencies with multiple build types, select 'debug' first, and 'release' in case 'debug' is missing
      selectBuildTypeFrom.set(listOf("debug", "release"))

      // For dependencies with a 'type' flavor dimension...
      productFlavorDimension("type") {
        // ...select the 'typeone' flavor.
        selectFrom.set(listOf("typeone"))
      }
    }
  }
}

9. Menambahkan dependensi pratinjau Compose

Biasanya, kita ingin memiliki library tertentu yang dicakupkan ke lingkungan pengembangan lokal untuk mencegah alat internal bocor ke artefak yang dipublikasikan akhir. Hal ini menjadi tantangan dengan plugin Android KMP baru karena plugin ini menghapus arsitektur jenis build yang digunakan untuk memisahkan dependensi pengembangan dari kode rilis.

// build.gradle.kts
dependencies {
  "androidRuntimeClasspath"(libs.androidx.compose.ui.tooling)
}

// build.gradle.kts
dependencies {
  debugImplementation(libs.androidx.compose.ui.tooling)
}

10. Mengonfigurasi target JVM untuk target Android KMP

Plugin Android KMP menetapkan target JVM menggunakan android.compilerOptions.jvmTarget, yang berlaku untuk Java dan Kotlin, sehingga menyederhanakan konfigurasi dibandingkan dengan blok compileOptions dan kotlinOptions terpisah dalam project Android murni.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

// build.gradle.kts
kotlin {
    android {
        compilerOptions {
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }
}

// build.gradle.kts
kotlin {
    android {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
            }
        }
    }
}

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

// build.gradle.kts
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. Memublikasikan aturan penyimpanan konsumen

Jika library KMP Anda perlu mengirimkan aturan keep konsumen (seperti aturan ProGuard untuk R8) bagi konsumennya, Anda harus secara eksplisit mengaktifkan publikasi dengan plugin baru. Sebelumnya, aturan keep konsumen dipublikasikan secara default jika ditentukan.

// build.gradle.kts
kotlin {
  android {
    optimization {
      consumerKeepRules.apply {
        publish = true
        file("consumer-proguard-rules.pro")
      }
    }
  }
}

// build.gradle.kts
android {
  defaultConfig {
    consumerProguardFiles("consumer-proguard-rules.pro")
  }
}

12. Memublikasikan library ke Maven

Jika Anda berencana memublikasikan library KMP ke Maven untuk digunakan oleh project lain, prosesnya akan berbeda bergantung pada apakah Anda menggunakan plugin Android-KMP baru atau plugin lama.

Referensi API plugin

Plugin baru ini memiliki platform API yang berbeda dengan com.android.library. Untuk informasi mendetail tentang DSL dan antarmuka baru, lihat referensi API:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Masalah umum pada plugin library Android-KMP

Berikut adalah masalah umum yang mungkin terjadi saat Anda menerapkan plugin com.android.kotlin.multiplatform.library baru:

• Pratinjau Compose gagal saat menggunakan plugin android-KMP baru

  • Diperbaiki di Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 dan Android Gradle Plugin 9.0.0-alpha13

• NullPointerException di pratinjau Compose Multiplatform dengan plugin com.android.kotlin.multiplatform.library

  • Diperbaiki di Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 dan Android Gradle Plugin 9.0.0-alpha13

• KMP menyimpan resolusi dependensi kompilasi umum di cache Konfigurasi, yang menyebabkan error saat melakukan deserialisasi (khusus Android)

  • Diperbaiki di Kotlin Gradle Plugin 2.3.0-Beta2

• Mendukung sourceSetTree berinstrumen untuk target androidLibrary

  • Diperbaiki di Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 dan Android Gradle Plugin 9.0.0-alpha13