迁移到 Android-KMP 库插件

Kotlin Multiplatform 具有用于配置库模块的 Gradle 插件。

com.android.kotlin.multiplatform.library 插件是官方替代方案，可取代之前使用常规 Android 库 Gradle 插件 (com.android.library) 将 Android 目标平台添加到 KMP 库的方法。

之前的做法现已弃用，取而代之的是插件（也称为 Android-KMP 插件）。继续使用 KMP 的 com.android.library 插件将不再受 JetBrains 支持，并且无法受益于未来的更新和改进。

注意： 使用 com.android.application 配置 Android 应用模块的方式不会发生变化。

如需迁移到此插件，请参阅应用 Android-KMP 插件部分。

主要功能和区别

Android-KMP 插件专门针对 KMP 项目量身打造，在几个关键方面与标准 com.android.library 插件有所不同：

• 单变体架构：插件使用单个变体，不再支持产品变种和 build 类型，从而简化配置并提升 build 性能。

• 针对 KMP 进行了优化：该插件专为 KMP 库设计，侧重于共享 Kotlin 代码和互操作性，省略了对特定于 Android 的原生 build、AIDL 和 RenderScript 的支持。

• 默认停用的测试：默认情况下，单元测试和设备（插桩）测试均处于停用状态，以提高 build 速度。您可以根据需要启用它们。

• 没有顶级 Android 扩展程序：配置通过 Gradle KMP DSL 中的 androidLibrary 代码块处理，从而保持一致的 KMP 项目结构。没有顶级 android 扩展块。

• 选择启用 Java 编译：Java 编译默认处于停用状态。在 androidLibrary 块中使用 withJava() 即可启用该功能。这样可以缩短不需要 Java 编译时的构建时间。

Android-KMP 库插件的优势

Android-KMP 插件可为 KMP 项目带来以下好处：

• 提升了构建性能和稳定性：它经过精心设计，可优化 KMP 项目中的构建速度并提高稳定性。它专注于 KMP 工作流，有助于提高构建流程的效率和可靠性。

• 增强的 IDE 集成：在处理 KMP Android 库时，可提供更好的代码补全、导航、调试和整体开发者体验。

• 简化的项目配置：该插件通过移除 build 变体等特定于 Android 的复杂性，简化了 KMP 项目的配置。这有助于生成更简洁且更易于维护的 build 文件。 之前，在 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 文件中应用插件声明。打开位于项目根目录中的 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 库模块 build 文件中应用插件。打开 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 项目以应用更改。