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.

Pendekatan sebelumnya kini tidak digunakan lagi dan digantikan dengan plugin, yang juga disebut sebagai plugin Android-KMP. Penggunaan plugin com.android.library untuk KMP tidak akan lagi didukung oleh JetBrains dan tidak akan mendapatkan manfaat dari update dan peningkatan di masa mendatang.

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

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 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 tidak mendukung 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 tingkat atas: Konfigurasi ditangani dengan blok androidLibrary dalam DSL KMP Gradle, sehingga mempertahankan struktur project KMP yang konsisten. Tidak ada pemblokiran ekstensi android tingkat teratas.

• Kompilasi Java keikutsertaan: Kompilasi Java dinonaktifkan secara default. Gunakan withJava() di blok androidLibrary 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: Dibuat 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: Memberikan pelengkapan kode, navigasi, proses debug, dan pengalaman developer yang lebih baik secara keseluruhan saat bekerja dengan 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 mudah dipelihara. Sebelumnya, penggunaan plugin com.android.library di 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.

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 = "8.13.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 dalam file build root. Buka file build.gradle.kts yang ada 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. Terapkan 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. Konfigurasi target KMP Android. Konfigurasi blok Multiplatform Kotlin (kotlin) untuk menentukan target Android. Dalam blok kotlin, tentukan target Android menggunakan 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. 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. Mendeklarasikan Dependensi

Tugas umum adalah mendeklarasikan dependensi untuk set sumber khusus Android. Plugin baru mengharuskan elemen 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 {
    androidLibrary {
        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")
}

2. Mengaktifkan Resource Android

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

3. Mengonfigurasi Pengujian Host dan Perangkat

Perubahan signifikan pada plugin baru ini adalah pengujian sisi host (unit) dan sisi perangkat (berinstrumen) Android dinonaktifkan secara default. Anda harus memilih ikut serta 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 = "ANDROIDX_TEST_ORCHESTRATOR"
    }
  }
}

// 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 = "ANDROIDX_TEST_ORCHESTRATOR"
  }
}

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

4. 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 mengaktifkan kompilasi untuk file Java yang berada langsung di dalam project Anda, bukan untuk dependensinya. Metode untuk menyetel 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"
    }
  }
}

5. 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.

Akibatnya, 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 ->
    // ...
  }
}

6. 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, free/paid ragam produk). 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"))
      }
    }
  }
}

Referensi Plugin API

Plugin baru 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