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 Multiplatform Kotlin (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 Android Gradle Plugin API 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 kemampuan di Android Studio, lihat Memperluas Mode Agen dengan kemampuan. Perlu diingat bahwa hasil AI tidak sepenuhnya dapat diprediksi.

Fitur dan perbedaan utama

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

• Arsitektur varian tunggal: Plugin ini menggunakan satu varian, 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 berfokus 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 Gradle KMP DSL, yang mempertahankan struktur project KMP yang konsisten. Tidak ada blok ekstensi android level teratas.

• Kompilasi Java keikutsertaan: 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: Plugin ini dirancang untuk kecepatan build yang dioptimalkan dan peningkatan stabilitas dalam project KMP. Fokusnya pada alur kerja KMP berkontribusi pada proses build yang lebih efisien dan andal.

• Integrasi IDE yang ditingkatkan: Plugin ini memberikan pelengkapan kode, navigasi, proses debug, dan pengalaman developer secara keseluruhan yang lebih baik 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 bersih dan lebih 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 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 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 Multiplatform Kotlin Anda. Untuk mengetahui detail selengkapnya, lihat Membuat library Android dan Mengonfigurasi varian build.

• Data binding dan View binding

  Ini adalah fitur framework UI khusus Android yang digabungkan secara erat dengan sistem Tampilan Android dan tata letak XML. Di plugin library Android-KMP baru, sebaiknya tangani UI menggunakan framework multiplatform seperti Compose Multiplatform. Data binding dan View binding dianggap sebagai detail implementasi aplikasi Android akhir, bukan library yang dapat dibagikan.

• Dukungan build native

  Plugin baru 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) serta kemampuan C-interop-nya. Jika Anda perlu menyertakan kode C/C++ native, Anda harus menentukannya sebagai bagian dari set sumber umum atau native dan mengonfigurasi C-interop 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 menggunakan library mandiri tersebut dari set sumber androidMain project library Multiplatform Kotlin 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 baru tidak bergantung pada varian dan tidak memiliki dukungan untuk 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
• Plugin Gradle Kotlin (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 dalam 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.2.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. Menerapkan deklarasi plugin dalam file build root. Buka file build.gradle.kts yang terletak di direktori root 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. Menerapkan plugin dalam file build modul library KMP. Buka file build.gradle.kts di modul library KMP Anda 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. Mengonfigurasi target Android KMP. 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. Menerapkan 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, sehingga Anda harus memindahkan sumber dari src/main ke src/androidMain, dari src/test ke src/androidHostTest, dan dari src/androidTest ke src/androidDeviceTest.

2. 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")
}

3. Mengaktifkan Resource Android

Dukungan untuk Resource Android (folder res) tidak diaktifkan secara default di plugin baru untuk mengoptimalkan performa build. Anda harus mengaktifkannya 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

4. Mengonfigurasi Pengujian Host dan Perangkat

Perubahan signifikan dalam plugin baru adalah bahwa pengujian sisi host (unit) dan sisi perangkat (instrumentasi) Android dinonaktifkan secara default. Anda harus mengaktifkannya secara eksplisit untuk membuat set sumber dan konfigurasi pengujian, sedangkan plugin lama membuatnya secara otomatis.

Model keikutsertaan ini membantu memverifikasi 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

5. 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 hal ini mengaktifkan kompilasi untuk file Java yang terletak langsung 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"
    }
  }
}

6. 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 ->
    // ...
  }
}

7. 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"))
      }
    }
  }
}

8. Dependensi pratinjau Compose

Biasanya, kita ingin memiliki library tertentu yang dicakup 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)
}

9. 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"
    }
}

10. Memublikasikan aturan keep konsumen

Jika library KMP Anda perlu mengirimkan aturan keep konsumen (seperti aturan ProGuard untuk R8) bagi konsumennya, Anda harus mengaktifkan publikasi secara eksplisit di 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")
  }
}

11. Memublikasikan library Anda 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 memiliki platform API yang berbeda dari com.android.library. Untuk mengetahui informasi mendetail tentang DSL dan antarmuka baru, lihat referensi API:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Masalah umum di 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 dalam pratinjau Multiplatform Compose 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 dalam cache Konfigurasi yang menyebabkan error saat mendeserialisasi (khusus Android)

  • Diperbaiki di Kotlin Gradle Plugin 2.3.0-Beta2

• Mendukung instrumented sourceSetTree untuk target androidLibrary

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