Kotlin Multiplatform 项目结构的基础知识

共通代码(Common Code)

fun greeting() {
    println("Hello, Kotlin Multiplatform!")
}

在平台之间共用的 Kotlin 代码通常位于 commonMain 目录中. 代码文件的位置是很重要的, 它会影响到这些代码编译到哪些平台.

Kotlin 编译器以源代码作为输入, 生成一组平台相关的二进制文件作为结果. 在编译跨平台项目时, 它可以从相同的代码生成多个二进制文件. 例如, 编译器可以从相同的 Kotlin 文件生成 JVM 的 .class 文件, 以及原生的可执行文件:

例如, 你不能在共通代码中使用 java.io.File 依赖项. 它是 JDK 的一部分, 而共通代码还会被编译为原生代码, 这种情况下就不能使用 JDK 的类:

例如, kotlinx.coroutines 是一个 Kotlin Multiplatform 库, 支持所有的编译目标, 但它还有一个平台相关的部分, 将 kotlinx.coroutines 的并发原语转换为 JDK 的并发原语, 例如 fun CoroutinesDispatcher.asExecutor(): Executor. API 的这些附加部分不能在 commonMain 中使用.

编译目标(Target)

你应该首先声明一个编译目标, 指示 Kotlin 为这个特定的目标平台编译代码. 在 Gradle 中, 你可以在 kotlin {} 代码段内使用预定义的 DSL 调用来声明编译目标:

kotlin {
    jvm() // 声明 JVM 编译目标
    iosArm64() // 声明对应于 64-bit iPhones 的编译目标
}

声明 jvm 和 iosArm64 编译目标之后, commonMain 中的共通代码将被编译到这些目标平台:

如果你还想将 greeting.kt 文件编译到 .js, 你只需要声明 JS 编译目标. commonMain 中的代码就会得到新的 js 标签, 对应于 JS 编译目标, 它会指示 Kotlin 生成 .js 文件:

源代码集(Source Set)

Kotlin 提供了一组预定义的源代码集. 其中一个是 commonMain, 它出现在所有的跨平台项目中, 并被编译到所有声明的编译目标.

在 Kotlin Multiplatform 项目中, 你可以将源代码集当作 src 中的目标. 例如, 一个项目有 commonMain, iosMain, 和 jvmMain 源代码集, 它的结构如下:

在 Gradle 脚本中, 你可以在 kotlin.sourceSets {} 代码段中通过名称访问源代码集:

kotlin {
    // 编译目标声明:
    // ...

    // 源代码集声明:
    sourceSets {
        commonMain {
            // 配置 commonMain 源代码集
        }
    }
}

除 commonMain 之外, 其他源代码集可以使平台相关的源代码集, 也可以是中间源代码集.

平台相关的源代码集

如果只有共通代码, 那将会非常便利, 但并不总是可行的. commonMain 中的代码会编译到所有声明的编译目标, 而 Kotlin 不允许你在共通代码中使用任何平台相关的 API.

在一个带有原生和 JS 编译目标的跨平台项目中, commonMain 中的以下代码将无法编译:

// commonMain/kotlin/common.kt
// 在共通代码中无法编译
fun greeting() {
    java.io.File("greeting.txt").writeText("Hello, Multiplatform!")
}

解决方案是, Kotlin 创建平台相关的源代码集, 也叫做平台源代码集. 每个编译目标有一个对应的平台源代码集, 这个源代码集只编译到这个编译目标. 例如, jvm 编译目标有对应的 jvmMain 源代码集, 这个源代码集只编译到 JVM. Kotlin 允许在这些源代码集中使用平台相关的依赖项, 例如, 在 jvmMain 中可以使用 JDK:

// jvmMain/kotlin/jvm.kt
// 你可以在 `jvmMain` 源代码集中使用 Java 依赖项
fun jvmGreeting() {
    java.io.File("greeting.txt").writeText("Hello, Multiplatform!")
}

中间源代码集

简单的跨平台项目通常只有共通代码和平台相关的代码. commonMain 源代码集代表共通代码, 在所有声明的编译目标之间共用. 平台相关的源代码集, 例如 jvmMain, 代表平台相关的代码, 只编译到各自的编译目标.

kotlin {
    androidTarget()
    iosArm64()   // 64 位 iPhone 设备
    macosArm64() // 现代的基于 Apple Silicon 的 Macs
    watchosX64() // 现代的 64 位 Apple Watch 设备
    tvosArm64()  // 现代的 Apple TV 设备
}

import platform.Foundation.NSUUID

fun randomUuidString(): String {
    // 你希望访问 Apple 专用的 API
    return NSUUID().UUIDString()
}

你不能将这个函数添加到 commonMain. commonMain 会编译到所有声明的编译目标, 包括 Android, 但 platform.Foundation.NSUUID 是一个 Apple 专用的 API, 在 Android 上无法使用. 如果你想要在 commonMain 中访问 NSUUID, Kotlin 会提示错误.

你可以将这段代码复制粘贴到每个 Apple 相关的源代码集: iosArm64Main, macosArm64Main, watchosX64Main, 和 tvosArm64Main. 但不推荐这样的方法, 因为这种重复的代码很容易导致错误.

appleMain 方块是 Kotlin 创建的一个中间源代码集, 用于共用那些编译到 Apple 相关编译目标的代码. appleMain 源代码集只编译到 Apple 编译目标. 因此, Kotlin 允许在 appleMain 中使用 Apple 专用的 API, 你可以将 randomUUID() 函数添加在这里.

在编译到特定的编译目标时, Kotlin 会得到所有的源代码集, 包括带有这个编译目标标签的中间源代码集. 因此, 在编译到 iosArm64 目标平台时, commonMain, appleMain, 和 iosArm64Main 源代码集中编写的所有代码会组合到一起:

与测试集成

除了 main 产品代码之外, 现实世界的项目还需要测试. 因此默认创建的所有源代码集都带有 Main 和 Test 后缀. Main 包含产品代码, Test 包含对产品代码的测试代码. 它们之间的连接会自动创建, 测试代码可以使用 Main 代码提供的 API, 不需要额外的配置.

对应的 Test 部分也是源代码集, 与 Main 类似. 例如, commonTest 对应于 commonMain, 并编译到所有声明的编译目标, 你可以用来编写共通的测试. 平台相关的测试源代码集, 例如 jvmTest, 用来编写平台相关的测试, 例如, JVM 相关的测试, 或需要 JVM API 的测试.

除了拥有源代码集来编写共通测试之外, 你还需要跨平台的测试框架. Kotlin 提供了一个默认的 kotlin.test 库, 其中有 @kotlin.Test 注解, 和各种断言方法, 例如 assertEquals 和 assertTrue.

对每个平台, 你可以在它们对应的源代码集中编写平台相关的测试, 和通常的测试一样. 和 main 代码一样, 你可以对每个源代码集设置平台相关的依赖项, 例如用于 JVM 的 JUnit, 和用于 iOS 的 XCTest. 要对特定的编译目标运行测试, 请使用 <targetName>Test task.

Kotlin Multiplatform 项目结构的基础知识﻿

共通代码(Common Code)﻿

编译目标(Target)﻿

note

源代码集(Source Set)﻿

平台相关的源代码集﻿

编译到特定的编译目标﻿

中间源代码集﻿

tip

tip

Apple 设备与模拟器的编译目标﻿

与测试集成﻿

下一步做什么?﻿

共通代码(Common Code)

编译目标(Target)

源代码集(Source Set)

平台相关的源代码集

编译到特定的编译目标

中间源代码集

Apple 设备与模拟器的编译目标

与测试集成

下一步做什么?