迁移到 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 库项目中常见的产品变种和 build 类型的支持，简化了构建流程。这简化了配置，并提升了 KMP Android 库的构建性能。
  • 针对 KMP 进行了优化：该插件专为 Kotlin Multiplatform 库而设计，侧重于共享 Kotlin 代码和互操作性。因此，它省略了对 Android 专用原生 build、AIDL（Android 接口定义语言）和 RenderScript 的支持，这些内容通常与 KMP 共享代码上下文无关。
  • 默认停用测试：为了进一步提高多平台环境中的构建速度，默认情况下测试处于停用状态。如果您的项目需要，您可以明确启用测试。这适用于主机上的测试（单元测试）和设备上的测试（插桩测试）。
  • 无顶级 Android 扩展：该插件不会在 Gradle build 文件中创建顶级 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 项目的配置。这会使 build 文件更简洁、更易于维护，并缩短刚开始接触 KMP Android 开发的开发者的学习曲线。以前，使用 com.android.library 插件将 Android 集成到 KMP 项目中时，Android Gradle 插件与多平台结构中的 Kotlin Gradle 插件之间的相互作用有时会导致源代码集名称出现误导性。例如，专用于配置 Android 插桩测试的源代码集名为 androidAndroidTest。对于熟悉标准 KMP 项目结构的开发者而言，这种命名惯例不太直观。
  • 官方推荐的解决方案：com.android.kotlin.multiplatform.library 插件是之前使用 com.android.library 插件将 Android 目标添加到 KMP 库的方法的官方替代方案。JetBrains 不再支持继续使用适用于 KMP 的 com.android.library 插件，并且您将无法获享未来的更新和改进。

将 Android-KMP 插件应用于项目

您可以通过以下两种主要方式将 Android-KMP 插件应用于项目： * 对于现有的 KMP 库模块，请手动修改 Gradle 文件。* 对于新的 KMP 库模块，请从 Android Studio 界面直接创建新模块。

将插件应用于现有模块

如需将 Android-KMP 插件应用于现有 KMP 库模块，请按以下步骤操作：

  1. 打开版本目录 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. 打开 KMP 库模块根目录中的 build.gradle.kts (Kotlin) 或 build.gradle (Groovy) 文件。

  3. 在文件顶部的 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
}

  4. 配置 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 多平台文档。