迁移到 Android-KMP 插件

此前，将 Android 集成到 KMP 项目中的唯一方法是使用常规的 Android 库 Gradle 插件：com.android.library。然而，此方法现已弃用，取而代之的是专用的 com.android.kotlin.multiplatform.library 插件，也称为 Android-KMP 插件。本指南介绍如何迁移到新插件。

主要功能和差异

Android-KMP 插件（com.android.kotlin.multiplatform.library）专为 KMP 项目量身定制，与传统的 com.android.library 插件在几个关键方面有所不同：

• 单变体架构：该插件以单个变体运行，通过移除对标准 Android 库项目中常见的产品变种和构建类型的支持，简化了构建过程。这简化了 KMP Android 库的配置并增强了构建性能。
• 为 KMP 优化：该插件专为 Kotlin Multiplatform 库设计，侧重于共享 Kotlin 代码和互操作性。因此，它省略了对 Android 特定的原生构建、AIDL (Android 接口定义语言) 和 RenderScript 的支持，这些在 KMP 共享代码环境中通常不相关。
• 默认禁用测试：为了进一步提高多平台环境中的构建速度，测试默认处于禁用状态。如果您的项目需要，可以显式启用测试。这适用于主机上的测试（单元测试）和设备上的测试（插桩测试）。
• 无顶级 Android 扩展：该插件不会在您的 Gradle 构建文件中创建顶级 android 扩展。配置通过 Kotlin 多平台 DSL 中的 androidLibrary 块处理，保持一致的 KMP 项目结构。
• 可选的 Java 编译：Java 编译默认未启用。如果您的 KMP 库需要编译基于 Java 的代码，您必须在 kotlin 块的 androidLibrary 配置块中显式使用 withJava() API 选择启用。这允许对编译过程进行更精细的控制，并且在不需要编译基于 Java 的代码时可以缩短构建时间。

迁移的好处

Android-KMP 插件为 KMP 项目提供以下好处：

• 改进的构建性能和稳定性：Android-KMP 插件旨在优化 KMP 项目中的构建速度和增强稳定性。其简化的架构和对 KMP 工作流的关注有助于实现更高效、更可靠的构建过程。
• 增强的 IDE 集成：该插件与 Android Studio 和其他 Kotlin IDE 提供了卓越的集成。这在使用 KMP Android 库时带来更好的代码补全、导航、调试和整体开发者体验。
• 简化的项目配置：通过移除 Android 特定的复杂性（如变体），Android-KMP 插件简化了 KMP 项目的配置。这带来了更清晰、更易于维护的构建文件，并降低了 KMP Android 开发新手的学习曲线。此前，当使用 com.android.library 插件将 Android 集成到 KMP 项目中时，Android Gradle 插件和 Kotlin Gradle 插件在多平台结构中的相互作用有时会导致误导性的源集名称。例如，用于配置 Android 插桩测试的源集被命名为 androidAndroidTest。这种命名约定对于熟悉标准 KMP 项目结构的开发者来说不太直观。
• 官方推荐解决方案：com.android.kotlin.multiplatform.library 插件是之前使用 com.android.library 插件向 KMP 库添加 Android 目标的官方替代方案。继续为 KMP 使用 com.android.library 插件将不再受 JetBrains 支持，并且不会受益于未来的更新和改进。

将 Android-KMP 插件应用于项目

有两种主要方法可以将 Android-KMP 插件应用于您的项目：

• 对于现有的 KMP 库模块，手动编辑您的 Gradle 文件。
• 对于新的 KMP 库模块，直接从 Android Studio UI 创建新模块。

将插件应用于现有模块

要将 Android-KMP 插件应用于现有 KMP 库模块，请遵循以下步骤：

1. 在版本目录中声明插件。打开版本目录 TOML 文件（通常是 gradle/libs.versions.toml），并将插件定义添加到 [plugins] 部分。

   [plugins]
   kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform",
   version.ref = "KOTLIN_PLUGIN_VERSION" }
   android-kotlin-multiplatform-library = { id =
   "com.android.kotlin.multiplatform.library", version.ref =
   "ANDROID_KMP_PLUGIN_VERSION" }
   

   将 KOTLIN_PLUGIN_VERSION 和 ANDROID_KMP_PLUGIN_VERSION 替换为您正在使用的实际版本。

2. 在根构建文件中应用插件声明。打开位于项目根目录下的 build.gradle.kts (Kotlin) 或 build.gradle (Groovy) 文件。使用 apply false 将插件别名添加到 plugins 块。这使得插件别名可用于所有子项目，而无需将插件逻辑应用于根项目本身。

   Kotlin

   plugins {
      alias(libs.plugins.kotlin.multiplatform) apply false
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library) apply false
   }

   Groovy

   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 (Kotlin) 或 build.gradle (Groovy) 文件。在文件的顶部，在 plugins 块内应用插件：

   Kotlin

   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

   Groovy

   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 项目以应用更改。

使用插件创建新模块

您也可以直接在 Android Studio 中创建新的 Kotlin Multiplatform 库模块。这将自动应用必要的插件，包括 Android-KMP 插件。有关如何使用 Android Studio 创建新的 KMP 库模块的更多指导，请参阅向现有项目添加 Kotlin Multiplatform。

有关整个多平台生态系统和更高级配置的更多信息，请参阅官方Kotlin Multiplatform 文档。