跨平台项目结构的高级概念

dependsOn 与源代码集层级关系

通常, 你会使用依赖项而不是 dependsOn 关系. 但是, 为了理解 Kotlin Multiplatform 项目的底层工作方式, 研究 dependsOn 是至关重要的.

dependsOn 是 2 个 Kotlin 源代码集之间的, Kotlin 特有的关系. 它可以是共通源代码集与平台相关源代码集之间的连接, 例如, 可以表示 jvmMain 源代码集依赖于 commonMain, iosArm64Main 依赖于 iosMain, 等等.

考虑一个一般的例子, 存在 Kotlin 源代码集 A 和 B. 表达式 A.dependsOn(B) 会指示 Kotlin:

dependsOn 关系会创建一个树形结构, 也叫做源代码集层级. 下面是一个通常的移动开发项目的例子, 针对的目标平台是 androidTarget, iosArm64 (iPhone 设备), 和 iosSimulatorArm64 (Apple Silicon Mac 上的 iPhone 模拟器):

图中的箭头表示 dependsOn 关系. 在编译平台二进制文件时, 也会保持这些关系. 所以 Kotlin 能够理解, iosMain 应该能够看到来自 commonMain 的 API, 但不能看到来自 iosArm64Main 的 API:

dependsOn 关系使用 KotlinSourceSet.dependsOn(KotlinSourceSet) 调用来配置, 例如:

kotlin {
    // 编译目标的声明
    sourceSets {
        // 配置 dependsOn 关系的示例
        iosArm64Main.dependsOn(commonMain)
    }
}

你不能使用 dependsOn 来声明对已发布的库或对另一个 Gradle 项目的通常的依赖项. 例如, 你不能设置 commonMain 依赖于 kotlinx-coroutines-core 库的 commonMain, 也不能调用 commonTest.dependsOn(commonMain).

声明自定义的源代码集

Kotlin 不会自动创建这样的源代码集. 因此你应该使用 by creating 构造来手动创建它:

kotlin {
    jvm()
    js()
    linuxX64()

    sourceSets {
        // 创建名为 "jvmAndJs" 的源代码集
        val jvmAndJsMain by creating {
            // ...
        }
    }
}

为了解决这个问题, 请添加几个 dependsOn 关系, 将 jvmAndJsMain 包含到层级结构中:

kotlin {
    jvm()
    js()
    linuxX64()

    sourceSets {
        val jvmAndJsMain by creating {
            // 不要忘记添加对 commonMain 的 dependsOn
            dependsOn(commonMain.get())
        }

        jvmMain {
            dependsOn(jvmAndJsMain)
        }

        jsMain {
            dependsOn(jvmAndJsMain)
        }
    }
}

这里, jvmMain.dependsOn(jvmAndJsMain) 会对 jvmAndJsMain 添加 JVM 编译目标, jsMain.dependsOn(jvmAndJsMain) 会对 jvmAndJsMain 添加 JS 编译目标.

对其他库或项目的依赖

跨平台项目中的依赖项配置有一些特别的功能. 每个 Kotlin 源代码集有它独自的 dependencies {} 代码块. 因此你可以在平台相关的源代码集中声明平台相关的依赖项:

kotlin {
    // 编译目标的声明
    sourceSets {
        jvmMain.dependencies {
            // 这是 jvmMain 的依赖项, 因此可以添加 JVM 相关的依赖项
            implementation("com.google.guava:guava:32.1.2-jre")
        }
    }
}

共通的依赖项要复杂一些. 考虑一个跨平台项目, 声明了对一个跨平台库的依赖项, 例如, kotlinx.coroutines:

kotlin {
    androidTarget()     // Android
    iosArm64()          // iPhone 设备
    iosSimulatorArm64() // Apple Silicon Mac 上的 iPhone 模拟器

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
        }
    }
}

跨平台依赖项会沿着 dependsOn 结构向下传播. 如果你对 commonMain 添加一个依赖项, 它会自动添加到声明了对 commonMain 直接或间接的 dependsOn 关系的所有源代码集.
在这个例子中, 依赖项实际会被自动添加到所有的 *Main 源代码集: iosMain, jvmMain, iosSimulatorArm64Main, 和 iosX64Main. 所有这些源代码集会从 commonMain 源代码集继承 kotlin-coroutines-core 依赖项, 因此你不需要将依赖项手动的复制粘贴到这些源代码集中:
tip
依赖项传播机制允许你通过选择特定的源代码集, 来指定接受到声明的依赖项的范围. 例如, 如果你希望在 iOS 上使用 kotlinx.coroutines, 但不在 Android 上使用, 你可以只对 iosMain 添加这个依赖项.
源代码集 -> 跨平台库依赖项, 例如上面的 commonMain 对 org.jetbrians.kotlinx:kotlinx-coroutines-core:1.7.3 的依赖, 表示依赖解析的中间状态. 解析的最终状态始终表示为源代码集 -> 源代码集依赖项.
note
最终的源代码集 -> 源代码集依赖项不是指 dependsOn 关系.
为了推断细粒度的源代码集 -> 源代码集依赖项, Kotlin 会读取和每个跨平台库一起发布的源代码集结构. 完成这一步之后, 每个库的内部表达不是一个整体, 而是它的源代码集的集合. 请看 kotlinx-coroutines-core 的例子:
Kotlin 对每个依赖关系解析为依赖项中源代码集的集合. 这个集合中的每个依赖项源代码集必须拥有兼容的编译目标. 依赖项源代码集拥有兼容的编译目标是指, 它至少编译到与使用它的源代码集相同的编译目标.
例如, 示例项目中的 commonMain 编译到 androidTarget, iosX64, 和 iosSimulatorArm64:
- 首先, 它解析到一个对 kotlinx-coroutines-core.commonMain 的依赖项. 因为 kotlinx-coroutines-core 编译到所有可能的 Kotlin 编译目标. 因此, 它的 commonMain 会编译到所有可能的编译目标, 包括这里要求的 androidTarget, iosX64, 和 iosSimulatorArm64.
- 其次, commonMain 依赖 kotlinx-coroutines-core.concurrentMain. 因为 kotlinx-coroutines-core 中的 concurrentMain 编译到除 JS 之外的所有的编译目标, 它匹配使用它的项目中的 commonMain 的编译目标.
但是, coroutines 中的 iosX64Main 之类的源代码集, 不兼容于使用它的 commonMain 源代码集. 即使 iosX64Main 编译到 commonMain 的编译目标之一, 也就是, iosX64, 但是它不编译到 androidTarget 或 iosSimulatorArm64.
依赖解析的结果直接影响可以访问 kotlinx-coroutines-core 中的哪些代码:

编译

Kotlin 编译会在编译目标之下分组. 默认情况下, Kotlin 为每个编译目标创建 2 个编译, main 编译用于产品源代码, test 编译用于测试源代码.

在构建脚本中, 编译通过类似的方式访问. 你首先选择一个 Kotlin 编译目标, 然后访问其中的 compilations 容器, 最后通过名称选择你需要的编译:

kotlin {
    // 声明并配置 JVM 编译目标
    jvm {
        val mainCompilation: KotlinJvmCompilation = compilations.getByName("main")
    }
}

跨平台项目结构的高级概念﻿

tip

dependsOn 与源代码集层级关系﻿

声明自定义的源代码集﻿

note

对其他库或项目的依赖﻿

tip

note

对齐跨源代码集的共通依赖项的版本﻿

编译﻿

dependsOn 与源代码集层级关系

声明自定义的源代码集

对其他库或项目的依赖

对齐跨源代码集的共通依赖项的版本

编译