遷移至 Android-KMP 程式庫外掛程式

Kotlin Multiplatform 具有 Gradle 外掛程式，可設定程式庫模組。

com.android.kotlin.multiplatform.library 外掛程式是官方替代方案，可取代先前使用一般 Android 程式庫 Gradle 外掛程式 (com.android.library) 將 Android 目標新增至 KMP 程式庫的方法。

我們已淘汰先前的做法，改用外掛程式 (也稱為 Android-KMP 外掛程式)。JetBrains 將不再支援繼續使用 KMP 外掛程式，且該外掛程式不會再有任何更新和改良。com.android.library

如要遷移至這個外掛程式，請參閱「套用 Android-KMP 外掛程式」一節。

主要功能和差異

Android-KMP 外掛程式專為 KMP 專案量身打造，與標準 com.android.library 外掛程式在幾個重要方面有所不同：

  • 單一變數架構：外掛程式會使用單一變數，移除對變種版本和建構類型的支援，簡化設定並提升建構效能。

  • 專為 KMP 最佳化：這個外掛程式專為 KMP 程式庫設計，著重於共用的 Kotlin 程式碼和互通性，省略對 Android 專用原生建構作業、AIDL 和 RenderScript 的支援。

  • 預設停用測試：為提升建構速度，單元和裝置 (檢測設備) 測試預設都會停用。您可以視需要啟用這些功能。

  • 沒有頂層 Android 擴充功能：設定是在 Gradle KMP DSL 內的 androidLibrary 區塊中處理，可維持一致的 KMP 專案結構。沒有頂層 android 擴充功能區塊。

  • 選擇啟用 Java 編譯：Java 編譯功能預設為停用。如要啟用，請在 androidLibrary 區塊中使用 withJava()。這樣一來，就不需要進行 Java 編譯，可縮短建構時間。

Android-KMP 程式庫外掛程式的優點

Android-KMP 外掛程式可為 KMP 專案提供下列優點：

  • 提升建構效能和穩定性：專為最佳化建構速度而設計，可提升 KMP 專案的穩定性。這項功能著重於 KMP 工作流程，有助於提升建構程序的效率和可靠性。

  • 強化 IDE 整合：使用 KMP Android 程式庫時，可提供更優質的程式碼完成、導覽、偵錯和整體開發人員體驗。

  • 簡化專案設定：這個外掛程式可移除建構變數等 Android 專屬的複雜項目，簡化 KMP 專案的設定。這樣一來，建構檔案就會更乾淨，也更容易維護。先前在 KMP 專案中使用 com.android.library 外掛程式時，可能會建立令人困惑的來源集名稱，例如 androidAndroidTest。對於熟悉標準 KMP 專案結構的開發人員來說，這個命名慣例較不直覺。

將 Android-KMP 外掛程式套用至現有模組

如要將 Android-KMP 外掛程式套用至現有的 KMP 程式庫模組，請按照下列步驟操作：

  1. 在版本目錄中聲明外掛程式。開啟版本目錄 TOML 檔案 (通常為 gradle/libs.versions.toml)，並新增外掛程式定義區段：

    # 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. 在根層級建構檔案中套用外掛程式宣告。開啟專案根目錄中的 build.gradle.kts 檔案。使用 apply false 將外掛程式別名新增至 plugins 區塊。這樣一來，所有子專案都能使用外掛程式別名，不必將外掛程式邏輯套用至根專案本身。

    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. 在 KMP 程式庫模組建構檔案中套用外掛程式。開啟 KMP 程式庫模組中的 build.gradle.kts 檔案，並在 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. 設定 Android KMP 目標。設定 Kotlin Multiplatform 區塊 (kotlin) 來定義 Android 目標。在 kotlin 區塊中，使用 androidLibrary 指定 Android 目標：

    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. 套用變更。套用外掛程式並設定 kotlin 區塊後，請同步處理 Gradle 專案以套用變更。