配置 Gradle 项目

Kotlin Gradle plugin 在项目中的数据

默认情况下, Kotlin Gradle plugin 会将项目相关的数据保存在项目根目录下的 .kotlin 目录中.

warning

不要将 .kotlin 目录提交到版本控制系统. 例如, 如果你在使用 Git, 请将 .kotlin 添加到你的项目的 .gitignore 文件中.

你可以将以下属性添加到你的项目的 gradle.properties 文件, 配置这些行为:

Kotlin 源代码与 Java 源代码

Kotlin 源代码与 Java 源代码可以保存在相同的目录下, 也可以放在不同的目录下.

默认的约定是使用不同的目录:

project
    - src
        - main (root)
            - kotlin
            - java

warning

不要将 Java 的 .java 文件放在 src/*/kotlin 目录中, 因为这样的 .java 文件不会被编译.

你应该改为放在 src/main/java 目录中.

如果不使用默认约定的文件夹结构, 那么需要修改相应的 sourceSets 属性:

sourceSets.main {
    java.srcDirs("src/main/myJava", "src/main/myKotlin")
}

sourceSets {
    main.kotlin.srcDirs += 'src/main/myKotlin'
    main.java.srcDirs += 'src/main/myJava'
}

对相关联的编译任务检查 JVM 编译目标的兼容性

在构建模块中, 你可能会有多个相互关联的编译任务, 比如:

• compileKotlin 与 compileJava

• compileTestKotlin 与 compileTestJava

note

main 与 test 源代码集的编译任务之间没有关联.

对于这种相互关联的编译任务, Kotlin Gradle plugin 会检查 JVM 编译目标的兼容性. kotlin 扩展或任务中的 jvmTarget 属性 和 java 扩展或任务中的 targetCompatibility 如果设置为不同的值, 会导致 JVM 编译目标不兼容. 例如: compileKotlin 任务设置为 jvmTarget=1.8, 而 compileJava 任务设置为 (或 继承得到) targetCompatibility=15.

要对整个项目的这个兼容性检查进行配置, 可以在 build.gradle(.kts) 文件中, 将 kotlin.jvm.target.validation.mode 属性设置为以下几个值:

• error – plugin 会让构建失败; 对于 Gradle 8.0 以上版本, 这是项目的默认值.

• warning – plugin 会输出警告信息; 对于低于 Gradle 8.0 的版本, 这是项目的默认值.

• ignore – plugin 会跳过检查, 不输出任何警告信息.

你也可以在你的 build.gradle(.kts) 文件中对各个编译任务单独进行配置:

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
    jvmTargetValidationMode.set(org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING)
}

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile.class).configureEach {
    jvmTargetValidationMode = org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING
}

要避免 JVM 编译目标不兼容, 需要 配置工具链, 或手动对齐(Align) JVM 版本.

plugins {
    kotlin("jvm") version "2.1.0"
}

plugins {
    id "org.jetbrains.kotlin.jvm" version "2.1.0"
}

Gradle Java 工具链支持

warning

给 Android 使用者的警告. 要使用 Gradle 工具链支持, 需要使用 Android Gradle plugin (AGP) 的 8.1.0-alpha09 或更高版本.

Gradle Java 工具链支持只在 AGP 7.4.0 以上版本 可用. 但是, 由于 这个问题, AGP 8.1.0-alpha09 以前的版本没有将 targetCompatibility 设置为等于工具链的 JDK. 如果你在使用低于 8.1.0-alpha09 的版本, 你需要通过 compileOptions 来手动配置 targetCompatibility. 请将占位符 <MAJOR_JDK_VERSION> 替换为你想要使用的 JDK 版本:

android {
    compileOptions {
        sourceCompatibility = <MAJOR_JDK_VERSION>
        targetCompatibility = <MAJOR_JDK_VERSION>
    }
}

Gradle 6.7 引入了 Java 工具链支持. 通过这个功能, 你可以:

• 使用与 Gradle 不同的 JDK 和 JRE 来运行编译, 测试, 以及可执行程序.

• 使用还未发布的语言版本编译和测试代码.

通过工具链支持, Gradle 能够自动查找本地的 JDK, 还能安装 Gradle 运行构建时需要的 JDK. 目前 Gradle 自身能够在任何 JDK 上运行, 而且还对依赖于主要 JDK 版本的任务重用 远程构建缓存功能.

Kotlin Gradle plugin 对 Kotlin/JVM 编译任务支持 Java 工具链. JS 和 Native 任务则不会使用工具链. Kotlin 编译器永远会在运行 Gradle daemon 的 JDK 上运行. Java 工具链会:

• 为 JVM 编译目标设置 -jdk-home 选项.

• 如果用户没有明确设置 jvmTarget 选项, 则将 compilerOptions.jvmTarget 设置为工具链的 JDK 版本. 如果用户没有配置工具链, 那么 jvmTarget 会使用默认值. 详情请参见 JVM 编译目标兼容性.

• 设置由任何 Java compile, test 和 javadoc 任务使用的工具链.

• 影响 kapt 任务执行器 使用哪个 JDK.

可以使用以下代码来设置工具链. 请将占位符 <MAJOR_JDK_VERSION> 替换为你想要使用的 JDK 版本:

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
    }
    // 或者使用更简短的写法:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 例如:
    jvmToolchain(17)
}

kotlin {
    jvmToolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
    // 或者使用更简短的写法:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 例如:
    jvmToolchain(17)
}

注意, 如果使用 kotlin 扩展设置工具链, 也会改变 Java 编译任务的工具链.

你可以通过 java 扩展设置工具链, Kotlin 编译任务会使用这个设置:

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
    }
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
}

如果你使用 Gradle 8.0.2 或更高版本, 你还需要添加一个 工具链解析器 plugin. 这种 plugin 会管理从哪个仓库下载工具链. 例如, 向你的 settings.gradle(.kts) 文件添加以下 plugin:

plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version("0.5.0")
}

plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '0.5.0'
}

关于与你的 Gradle 版本对应的 foojay-resolver-convention 版本, 请参见 Gradle 网站.

note

要确认 Gradle 使用哪个工具链, 请使用 log 级别 --info 来运行你的 Gradle 构建, 并在输出中查找 [KOTLIN] Kotlin compilation 'jdkHome' argument: 开头的字符串. 冒号之后的部分就是工具链使用的 JDK 版本.

要为特定的 Task 设置任意的 JDK (甚至本地 JDK), 请使用 Task DSL.

详情请参见 Kotlin plugin 中对 Gradle JVM 工具链的支持.

使用 Task DSL 设置 JDK 版本

Task DSL 可以对任何实现了 UsesKotlinJavaToolchain 接口的任务, 设置任意的 JDK 版本. 目前, 这些任务只有 KotlinCompile 和 KaptTask. 如果希望 Gradle 搜索主要的 JDK 版本, 请在你的构建脚本中替换 <MAJOR_JDK_VERSION> 占位符:

val service = project.extensions.getByType<JavaToolchainService>()
val customLauncher = service.launcherFor {
    languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
}
project.tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.toolchain.use(customLauncher)
}

JavaToolchainService service = project.getExtensions().getByType(JavaToolchainService.class)
Provider<JavaLauncher> customLauncher = service.launcherFor {
    it.languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
}
tasks.withType(UsesKotlinJavaToolchain::class).configureEach { task ->
    task.kotlinJavaToolchain.toolchain.use(customLauncher)
}

或者你特也可以指定你的本地 JDK 路径, 然后使用这个 JDK 版本替换 <LOCAL_JDK_VERSION> 占位符:

tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.jdk.use(
        "/path/to/local/jdk", // 这里设置你的 JDK 路径
        JavaVersion.<LOCAL_JDK_VERSION> // 例如, JavaVersion.17
    )
}

关联编译器任务

你可以将编译任务 关联(Associate) 在一起, 方法是在编译任务之间设置关联关系, 一个编译需要使用另一个编译的输出. 关联编译器任务会在编译任务之间建立 internal 的可见度.

Kotlin 编译器会默认的关联某些编译任务, 比如每个编译目标的 test 和 main 编译任务. 如果你需要表达你的某个自定义编译任务与其它编译任务相关联, 请创建你自己的编译任务关联.

要让 IDE 支持关联编译任务, 在源代码集之间推断可见度, 请向你的 build.gradle(.kts) 添加以下代码:

val integrationTestCompilation = kotlin.target.compilations.create("integrationTest") {
    associateWith(kotlin.target.compilations.getByName("main"))
}

integrationTestCompilation {
    kotlin.target.compilations.create("integrationTest") {
        associateWith(kotlin.target.compilations.getByName("main"))
    }
}

在这个例子中, integrationTest 编译任务关联到 main 编译任务, 可以在功能测试(集成测试)代码中访问 internal 对象.

Java Modules (JPMS) 启用时的配置

要让 Kotlin Gradle plugin 与 Java 模块(Module) 共通工作, 请向你的构建脚本添加以下内容, 并将其中的 YOUR_MODULE_NAME 替换为你的 JPMS 模块的引用, 例如, org.company.module:

// 如果你使用的 Gradle 版本低于 7.0, 请添加以下 3 行
java {
    modularity.inferModulePath.set(true)
}

tasks.named("compileJava", JavaCompile::class.java) {
    options.compilerArgumentProviders.add(CommandLineArgumentProvider {
        // 将编译后的 Kotlin 类提供给 to javac – 需要这样做才能让 Java/Kotlin 混合源代码正常工作
        listOf("--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}")
    })
}

// 如果你使用的 Gradle 版本低于 7.0, 请添加以下 3 行
java {
    modularity.inferModulePath = true
}

tasks.named("compileJava", JavaCompile.class) {
    options.compilerArgumentProviders.add(new CommandLineArgumentProvider() {
        @Override
        Iterable<String> asArguments() {
            // Provide compiled Kotlin classes to javac – 需要这样做才能让 Java/Kotlin 混合源代码正常工作
            return ["--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}"]
        }
    })
}

note

和通常一样, 请将 module-info.java 文件放在 src/main/java 目录内.

对于模块, Kotlin 文件中的包名称应该等于 module-info.java 中的包名称, 否则会出现构建错误 "package is empty or does not exist".

更多详情请参见:

• 为 Java 模块系统构建模块

• 使用 Java 模块系统构建应用程序

• "module" 在 Kotlin 中的意义

其他细节

详情请参见 Kotlin/JVM.

FAILURE: Build failed with an exception.

What went wrong:
Circular dependency between the following tasks:
:lib:compileKotlinJvm
--- :lib:jvmJar
     \--- :lib:compileKotlinJvm (*)
(*) - details omitted (listed previously)

kotlin.build.archivesTaskOutputAsFriendModule=false

tasks.jar(type: Jar) {
    from sourceSets.main.outputs
    from sourceSets.main.kotlin.classesDirectories
}

JavaScript 项目的 Kotlin 源代码与 Java 源代码

这个 plugin 只能编译 Kotlin 源代码文件, 因此推荐将 Kotlin 和 Java 源代码文件放在不同的文件夹内(如果工程内包含 Java 文件的话). 如果不将源代码分开存放, 请在 sourceSets{} 代码段中指定源代码文件夹:

kotlin {
    sourceSets["main"].apply {
        kotlin.srcDir("src/main/myKotlin")
    }
}

kotlin {
    sourceSets {
        main.kotlin.srcDirs += 'src/main/myKotlin'
    }
}

依赖项的类型

请根据你的需要选择依赖项的类型.

对标准库的依赖项

对每个源代码集(Source Set), 会自动添加对标准库 (stdlib) 的依赖项. 使用的标准库版本与 Kotlin Gradle plugin 版本相同.

对于与平台相关的源代码集, 会使用针对这个平台的标准库, 同时, 对其他源代码集会添加共通的标准库. Kotlin Gradle plugin 会根据你的 Gradle 构建脚本的 compilerOptions.jvmTarget 编译器选项 设置, 选择适当的 JVM 标准库.

如果明确的声明一个标准库依赖项(比如, 如果你需要使用不同的版本), Kotlin Gradle plugin 不会覆盖你的设置, 也不会添加第二个标准库.

如果你完全不需要标准库, 可以在你的 gradle.properties 文件中添加以下 Gradle 属性:

kotlin.stdlib.default.dependency=false

kotlin.stdlib.jdk.variants.version.alignment=false

设置对测试库的依赖项

对于支持的所有平台, Kotlin 项目的测试可以使用 kotlin.test API. 对 commonTest 源代码集添加 kotlin-test 依赖项, 然后 Gradle plugin 会为每个测试源代码集推断出对应的测试库依赖项.

Kotlin/Native 编译目标已经内建了 kotlin.test API 的实现, 不需要额外的测试依赖项.

kotlin {
    sourceSets {
        val commonTest by getting {
            dependencies {
                implementation(kotlin("test")) // 这个设置会自动引入对应平台的所有依赖项
            }
        }
    }
}

kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // 这个设置会自动引入对应平台的所有依赖项
            }
        }
    }
}

note

对 Kotlin 模块的依赖项, 可以使用简写, 比如, 对 "org.jetbrains.kotlin:kotlin-test" 的依赖项可以简写为 kotlin("test").

你也可以在任何共通源代码集或平台相关的源代码集中使用 kotlin-test 依赖项.

kotlin {
    jvm {
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    sourceSets {
        val commonTest by getting {
            dependencies {
                implementation(kotlin("test"))
            }
        }
    }
}

kotlin {
    jvm {
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test")
            }
        }
    }
}

dependencies {
    testImplementation(kotlin("test"))
}

tasks {
    test {
        useTestNG()
    }
}

dependencies {
    testImplementation 'org.jetbrains.kotlin:kotlin-test'
}

test {
    useTestNG()
}

kotlin.test.infer.jvm.variant=false

设置对 kotlinx 库的依赖项

如果使用 kotlinx 库, 并且需要与平台相关的依赖项, 那么可以通过 -jvm 或 -js 之类的后缀, 来指定与平台相关的库版本, 例如, kotlinx-coroutines-core-jvm. 也可以使用库的基本 artifact 名(base artifact name) – kotlinx-coroutines-core.

kotlin {
    sourceSets {
        val jvmMain by getting {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.9.0")
            }
        }
    }
}

kotlin {
    sourceSets {
        jvmMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.9.0'
            }
        }
    }
}

如果使用跨平台的库, 并且需要依赖共用代码, 那么只需要在共用源代码集中一次性设置依赖项. 请使用库的基本 artifact 名(base artifact name), 例如 kotlinx-coroutines-core 或 ktor-client-core.

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
            }
        }
    }
}

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0'
            }
        }
    }
}

在最顶层设置依赖项

另一种做法是, 可以在最顶层指定依赖项, 方法是使用 <sourceSetName><DependencyType> 格式的配置名称. 对于某些 Gradle 内建的依赖项, 比如 gradleApi(), localGroovy(), 或 gradleTestKit(), 这种方法会很有用, 这些依赖项在 Source Set 依赖项 DSL 中是不能使用的.

dependencies {
    "commonMainImplementation"("com.example:my-library:1.0")
}

dependencies {
    commonMainImplementation 'com.example:my-library:1.0'
}