設定 Gradle 專案
若要使用 Gradle 建置 Kotlin 專案, 你需要在建置指令碼檔案 build.gradle(.kts) 中套用 Kotlin Gradle 外掛程式, 並在其中設定專案的相依性。
若要進一步了解建置指令碼的內容, 請參閱探索建置指令碼章節。
套用外掛程式
若要套用 Kotlin Gradle 外掛程式,請使用 Gradle plugins DSL 中的 plugins{} 區塊:
plugins {
// 將 `<...>` 替換為適合你目標環境的外掛程式名稱
kotlin("<...>") version "2.4.21"
// 例如,如果你的目標環境是 JVM:
// kotlin("jvm") version "2.4.21"
}plugins {
// 將 `<...>` 替換為適合你目標環境的外掛程式名稱
id 'org.jetbrains.kotlin.<...>' version '2.4.21'
// 例如,如果你的目標環境是 JVM:
// id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}Kotlin Gradle 外掛程式 (KGP) 與 Kotlin 共用相同的版本編號。
在設定專案時,請檢查 Kotlin Gradle 外掛程式 (KGP) 與可用 Gradle 版本的相容性。 下表列出了 Gradle 和 Android Gradle 外掛程式 (AGP) 完全支援的最低與最高版本:
| KGP 版本 | Gradle 最低與最高版本 | AGP 最低與最高版本 |
|---|---|---|
| 2.4.20–2.4.21 | 7.6.3–9.7.0 | 8.5.2–9.3.1 |
| 2.4.0–2.4.10 | 7.6.3–9.5.0 | 8.5.2–9.1.0 |
| 2.3.20–2.3.21 | 7.6.3–9.3.0 | 8.2.2–9.0.0 |
| 2.3.10 | 7.6.3–9.0.0 | 8.2.2–9.0.0 |
| 2.3.0 | 7.6.3–9.0.0 | 8.2.2–8.13.0 |
| 2.2.20–2.2.21 | 7.6.3–8.14 | 7.3.1–8.11.1 |
| 2.2.0–2.2.10 | 7.6.3–8.14 | 7.3.1–8.10.0 |
| 2.1.20–2.1.21 | 7.6.3–8.12.1 | 7.3.1–8.7.2 |
| 2.1.0–2.1.10 | 7.6.3–8.10* | 7.3.1–8.7.2 |
| 2.0.20–2.0.21 | 6.8.3–8.8* | 7.1.3–8.5 |
| 2.0.0 | 6.8.3–8.5 | 7.1.3–8.3.1 |
| 1.9.20–1.9.25 | 6.8.3–8.1.1 | 4.2.2–8.1.0 |
*Kotlin 2.0.20–2.0.21 與 Kotlin 2.1.0–2.1.10 可完全相容至 Gradle 8.6。 Gradle 8.7–8.10 亦受支援,但只有一個例外:如果你使用 Kotlin Multiplatform Gradle 外掛程式, 在多平台專案中於 JVM 目標呼叫 withJava() 函式時,可能會看到棄用警告。 如需詳細資訊,請參閱預設建立的 Java 原始碼集。
你也可以使用最新發行版本的 Gradle 和 AGP,但若這樣做,請注意你可能會遇到棄用警告,或者某些新功能可能無法正常運作。
例如,Kotlin Gradle 外掛程式與 kotlin-multiplatform 外掛程式 2.4.21 需要最低 7.6.3 的 Gradle 版本才能編譯你的專案。
同樣地,完全支援的最高版本是 9.7.0。它沒有已棄用的 Gradle 方法與屬性,並且支援所有目前的 Gradle 功能。
較早的 KGP 版本
| KGP 版本 | Gradle 最低與最高版本 | AGP 最低與最高版本 |
|---|---|---|
| 1.9.0–1.9.10 | 6.8.3–7.6.0 | 4.2.2–7.4.0 |
| 1.8.20–1.8.22 | 6.8.3–7.6.0 | 4.1.3–7.4.0 |
| 1.8.0–1.8.11 | 6.8.3–7.3.3 | 4.1.3–7.2.1 |
| 1.7.20–1.7.22 | 6.7.1–7.1.1 | 3.6.4–7.0.4 |
| 1.7.0–1.7.10 | 6.7.1–7.0.2 | 3.4.3–7.0.2 |
| 1.6.20–1.6.21 | 6.1.1–7.0.2 | 3.4.3–7.0.2 |
專案中的 Kotlin Gradle 外掛程式資料
預設情況下,Kotlin Gradle 外掛程式會將專案特定的永續資料儲存在專案根目錄的 .kotlin 目錄中。
請勿將 .kotlin 目錄提交至版本控制系統。 例如,如果你使用 Git,請將 .kotlin 新增至專案的 .gitignore 檔案中。
你可以在專案的 gradle.properties 檔案中新增屬性來設定此行為:
| Gradle 屬性 | 說明 |
|---|---|
kotlin.project.persistent.dir | 設定專案層級資料的儲存位置。預設值:<project-root-directory>/.kotlin |
kotlin.project.persistent.dir.gradle.disableWrite | 控制是否停用將 Kotlin 資料寫入 .gradle 目錄(用於與舊版 IDEA 版本的回溯相容性)。預設值:false |
目標鎖定 JVM
若要以 JVM 為目標,請套用 Kotlin JVM 外掛程式。
plugins {
kotlin("jvm") version "2.4.21"
}plugins {
id "org.jetbrains.kotlin.jvm" version "2.4.21"
}在此區塊中,version 必須是常值,且無法從另一個建置指令碼套用。
Kotlin 與 Java 原始碼
Kotlin 原始碼與 Java 原始碼可以儲存在同一個目錄中,也可以放在不同的目錄中。
預設慣例是使用不同的目錄:
project
- src
- main (root)
- kotlin
- java請勿將 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與compileJavacompileTestKotlin與compileTestJava
main 與 test 原始碼集的編譯任務彼此是不相關的。
對於像這類相關的任務,Kotlin Gradle 外掛程式會檢查 JVM 目標相容性。如果在 kotlin 擴充套件或任務中的 jvmTarget 屬性 與 java 擴充套件或任務中的 targetCompatibility 設定了不同的值,將會導致 JVM 目標不相容。例如: compileKotlin 任務具有 jvmTarget=1.8,而 compileJava 任務具有(或繼承)targetCompatibility=15。
透過在 gradle.properties 檔案中設定 kotlin.jvm.target.validation.mode 屬性,可以設定整個專案此項檢查的行為:
error– 外掛程式使建置失敗;適用於 Gradle 8.0+ 專案的預設值。warning– 外掛程式印出警告訊息;適用於低於 Gradle 8.0 專案的預設值。ignore– 外掛程式跳過檢查且不產生任何訊息。
你也可以在 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 目標不相容,請設定工具鏈或手動對齊 JVM 版本。
如果目標不相容會發生什麼問題
有兩種手動設定 Kotlin 和 Java 原始碼集 JVM 目標的方法:
- 隱式方式:透過設定 Java 工具鏈。
- 顯式方式:透過在
kotlin擴充套件或任務中設定jvmTarget屬性,並在java擴充套件或任務中設定targetCompatibility。
如果你遇到以下情況,就會發生 JVM 目標不相容:
- 明確設定了不同的
jvmTarget和targetCompatibility值。 - 使用預設設定,且你的 JDK 不等於
1.8。
讓我們考慮建置指令碼中只有 Kotlin JVM 外掛程式且沒有額外 JVM 目標設定時的預設配置:
plugins {
kotlin("jvm") version "2.4.21"
}plugins {
id "org.jetbrains.kotlin.jvm" version "2.4.21"
}當建置指令碼中沒有關於 jvmTarget 值的明確資訊時,其預設值為 null, 且編譯器會將其轉換為預設值 1.8。而 targetCompatibility 等於 當前 Gradle 的 JDK 版本,也就是你的 JDK 版本(除非你使用 Java 工具鏈方式)。假設你的 JDK 版本是 17,你發布的程式庫構件將會聲明自身相容於 JDK 17+:org.gradle.jvm.version=17,這是不正確的。 在這種情況下,即使位元組碼的版本為 1.8,你也必須在主專案中使用 Java 17 才能新增此程式庫。設定工具鏈 即可解決此問題。
Gradle Java 工具鏈支援
Android 使用者注意事項:若要使用 Gradle 工具鏈支援,請使用 Android Gradle 外掛程式 (AGP) 8.1.0-alpha09 或更高版本。
Gradle Java 工具鏈支援僅從 AGP 7.4.0 起開始提供。 然而,由於此問題,在 8.1.0-alpha09 版本之前,AGP 並未將 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 外掛程式支援在 Kotlin/JVM 編譯任務中使用 Java 工具鏈。JS 和 Native 任務不使用工具鏈。 Kotlin 編譯器一律在 Gradle 常駐程式 (daemon) 所執行的 JDK 上執行。 Java 工具鏈:
- 設定適用於 JVM 目標的
-jdk-home選項。 - 如果使用者未明確設定
jvmTarget選項,則將compilerOptions.jvmTarget設定為工具鏈的 JDK 版本。 如果使用者未設定工具鏈,則jvmTarget欄位會使用預設值。 進一步了解 JVM 目標相容性。 - 設定任何 Java 編譯、測試和 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 或更高版本,你還需要新增工具鏈解析器外掛程式。 此類型的外掛程式管理要從哪些存放庫下載工具鏈。舉例來說,將以下外掛程式新增至你的 settings.gradle(.kts):
plugins {
id("org.gradle.toolchains.foojay-resolver-convention") version("1.0.0")
}plugins {
id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
}請在 Gradle 網站上檢查 foojay-resolver-convention 的版本是否對應於你的 Gradle 版本。
若要了解 Gradle 使用了哪一個工具鏈,請以記錄層級 --info 執行你的 Gradle 建置,並在輸出中尋找以 [KOTLIN] Kotlin compilation 'jdkHome' argument: 開頭的字串。 冒號後面的部分即為來自工具鏈的 JDK 版本。
若要為特定任務設定任何 JDK(甚至是本機 JDK),請使用 Task DSL。
進一步了解 Kotlin 外掛程式中的 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 的路徑,並將占位符號 <LOCAL_JDK_VERSION> 替換為該 JDK 版本:
tasks.withType<UsesKotlinJavaToolchain>().configureEach {
kotlinJavaToolchain.jdk.use(
"/path/to/local/jdk", // 填入你的 JDK 路徑
JavaVersion.<LOCAL_JDK_VERSION> // 例如,JavaVersion.17
)
}關聯編譯器任務
你可以透過建立編譯任務之間的關係來關聯編譯,使一個編譯任務使用另一個編譯任務的編譯輸出。 關聯編譯會在它們之間建立 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 模組 (JPMS) 的情況下進行設定
若要使 Kotlin Gradle 外掛程式與 Java 模組搭配運作, 請在建置指令碼中新增以下內容,並將 YOUR_MODULE_NAME 替換為你的 JPMS 模組參照,例如 org.company.module:
tasks.named("compileJava", JavaCompile::class.java) {
// 將編譯後的 Kotlin 類別提供給 javac – 這是 Java/Kotlin 混合原始碼正常運作所必需的
val mainOutput: FileCollection = sourceSets["main"].output
options.compilerArgumentProviders.add(CommandLineArgumentProvider {
listOf("--patch-module", "YOUR_MODULE_NAME=${mainOutput.asPath}")
})
}tasks.named("compileJava", JavaCompile.class) {
// 將編譯後的 Kotlin 類別提供給 javac – 這是 Java/Kotlin 混合原始碼正常運作所必需的
FileCollection mainOutput = sourceSets["main"].output
options.compilerArgumentProviders.add(new CommandLineArgumentProvider() {
@Override
Iterable<String> asArguments() {
return ["--patch-module", "YOUR_MODULE_NAME=${mainOutput.asPath}"]
}
})
}照常將 module-info.java 放入 src/main/java 目錄中。
對於模組而言,Kotlin 檔案中的套件名稱應等於 module-info.java 中的套件名稱,以避免出現「package is empty or does not exist」建置失敗。
進一步了解:
其他詳細資訊
停用編譯任務中的構件使用
在極少數情況下,你可能會遇到由循環相依錯誤導致的建置失敗。例如,當你有多個編譯任務, 其中一個編譯可以看見另一個編譯的所有內部宣告,而產生的構件又依賴於這兩個編譯任務的輸出:
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)為了修復此循環相依錯誤,我們新增了一個 Gradle 屬性:archivesTaskOutputAsFriendModule。 此屬性控制編譯任務中構件輸入的使用,並決定是否因此建立任務相依性。
預設情況下,此屬性設為 true 以追蹤任務相依性。如果你遇到循環相依錯誤, 可以在編譯任務中停用構件的使用,以移除任務相依性並避免循環相依錯誤。
若要在編譯任務中停用構件的使用,請在 gradle.properties 檔案中新增以下內容:
kotlin.build.archivesTaskOutputAsFriendModule=false延遲建立 Kotlin/JVM 任務
從 Kotlin 1.8.20 開始,Kotlin Gradle 外掛程式會註冊所有任務,並且在試執行 (dry run) 時不會對它們進行設定。
編譯任務 destinationDirectory 的非預設位置
如果你覆寫了 Kotlin/JVM KotlinJvmCompile/KotlinCompile 任務的 destinationDirectory 位置, 請更新你的建置指令碼。你需要明確地將 sourceSets.main.kotlin.classesDirectories 新增至 JAR 檔案中的 sourceSets.main.outputs:
tasks.jar(type: Jar) {
from sourceSets.main.outputs
from sourceSets.main.kotlin.classesDirectories
}目標鎖定多平台
鎖定多平台的專案(稱為多平台專案) 需要 kotlin-multiplatform 外掛程式。
kotlin-multiplatform 外掛程式適用於 Gradle 7.6.3 或更高版本。
plugins {
kotlin("multiplatform") version "2.4.21"
}plugins {
id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}進一步了解適用於不同平台的 Kotlin Multiplatform 以及 適用於 iOS 和 Android 的 Kotlin Multiplatform。
目標鎖定 Android
建議使用 Android Studio 來建立 Android 應用程式。了解如何使用 Android Gradle 外掛程式。
目標鎖定 Web
Kotlin 透過 Kotlin Multiplatform 為 Web 開發提供兩種途徑:
- 基於 JavaScript(使用 Kotlin/JS 編譯器)
- 基於 WebAssembly(使用 Kotlin/Wasm 編譯器)
兩種途徑均使用 Kotlin Multiplatform 外掛程式,但支援不同的使用案例。 以下各節將說明如何在 Gradle 建置中設定每個目標以及何時使用它們。
目標鎖定 JavaScript
如果你的目標是進行以下作業,請使用 Kotlin/JS:
- 與 JavaScript/TypeScript 程式碼庫共用商務邏輯
- 使用 Kotlin 建置不可共用的 Web 應用程式
如需詳細資訊,請參閱 Web 開發。
當以 JavaScript 為目標時,請使用 kotlin-multiplatform 外掛程式:
plugins {
kotlin("multiplatform") version "2.4.21"
}plugins {
id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}透過指定應在瀏覽器還是 Node.js 環境中執行來設定 JavaScript 目標:
kotlin {
js().browser { // 或 js().nodejs
/* ... */
}
}目標鎖定 WebAssembly
如果你希望在多個平台之間共用邏輯和 UI,請使用 Kotlin/Wasm。如需詳細資訊, 請參閱 Web 開發。
與 JavaScript 一樣,以 WebAssembly (Wasm) 為目標時,請使用 kotlin-multiplatform 外掛程式:
plugins {
kotlin("multiplatform") version "2.4.21"
}plugins {
id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}根據你的需求,你可以鎖定以下目標:
wasmJs:用於在瀏覽器或 Node.js 中執行wasmWasi:用於在支援 WASI (WebAssembly System Interface) 的 Wasm 環境中執行,例如 Wasmtime、WasmEdge 等。
為網頁瀏覽器或 Node.js 設定 wasmJs 目標:
kotlin {
wasmJs {
browser { // 或 nodejs
/* ... */
}
}
}對於 WASI 環境,請使用 Node.js 或 Wasmtime 設定 wasmWasi 目標:
kotlin {
wasmWasi {
nodejs { // 或 wasmtime
/* ... */
}
}
}Web 目標的 Kotlin 與 Java 原始碼
KGP 僅適用於 Kotlin 檔案,因此建議你將 Kotlin 與 Java 檔案分開存放(如果專案包含 Java 檔案)。如果不分開存放,請在 sourceSets{} 區塊中指定原始碼資料夾:
kotlin {
sourceSets["main"].apply {
kotlin.srcDir("src/main/myKotlin")
}
}kotlin {
sourceSets {
main.kotlin.srcDirs += 'src/main/myKotlin'
}
}使用 KotlinBasePlugin 介面觸發設定操作
每當套用任何 Kotlin Gradle 外掛程式(JVM、JS、Multiplatform、Native 等)時,若要觸發某些設定操作, 請使用所有 Kotlin 外掛程式所繼承的 KotlinBasePlugin 介面:
import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin
// ...
project.plugins.withType<KotlinBasePlugin>() {
// 在此處設定你的操作
}import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin
// ...
project.plugins.withType(KotlinBasePlugin.class) {
// 在此處設定你的操作
}設定相依性
若要新增對程式庫的相依性,請在原始碼集 DSL 的 dependencies{} 區塊中設定所需類型的相依性(例如 implementation)。
kotlin {
sourceSets {
commonMain.dependencies {
implementation("com.example:my-library:1.0")
}
}
}kotlin {
sourceSets {
commonMain {
dependencies {
implementation 'com.example:my-library:1.0'
}
}
}
}在最頂層設定相依性
你可以使用頂層 dependencies {} 區塊在多平台專案中設定共用相依性。 在此宣告的相依性運作方式就如同將它們新增到 commonMain 或 commonTest 原始碼集中一樣。
若要使用頂層 dependencies {} 區塊,請在該區塊前新增 @OptIn(ExperimentalKotlinGradlePluginApi::class) 註解以選擇加入:
kotlin {
@OptIn(ExperimentalKotlinGradlePluginApi::class)
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}
}kotlin {
dependencies {
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
}
}在對應目標的 sourceSets {} 區塊內新增特定於平台的相依性。
你可以在 YouTrack 上分享你對此功能的回饋。
相依性類型
根據你的需求選擇相依性類型。
| 類型 | 說明 | 何時使用 |
|---|---|---|
api | 在編譯期間和執行階段都會使用,並匯出給程式庫使用者。 | 如果來自相依性的任何型別用於目前模組的公用 API 中,請使用 api 相依性。 |
implementation | 在目前模組的編譯期間和執行階段使用,但不會對相依於包含 implementation 相依性模組的其他模組公開編譯。 | 用於模組內部邏輯所需的相依性。 如果模組是不發布的終端應用程式,請使用 |
compileOnly | 用於目前模組的編譯,在執行階段以及其他模組編譯期間均不可用。 | 用於在執行階段具有可用第三方實作的 API。 |
runtimeOnly | 在執行階段可用,但在任何模組的編譯期間均不可見。 |
標準程式庫的相依性
每個原始碼集都會自動新增對標準程式庫 (stdlib) 的相依性。所使用的標準程式庫版本與 Kotlin Gradle 外掛程式的版本相同。
對於平台專屬的原始碼集,會使用該程式庫對應的平台專屬變體,而其餘原始碼集則新增通用標準程式庫。Kotlin Gradle 外掛程式會根據 Gradle 建置指令碼的 compilerOptions.jvmTarget 編譯器選項來選擇適當的 JVM 標準程式庫。
如果你明確宣告標準程式庫相依性(例如,如果你需要不同的版本),Kotlin Gradle 外掛程式不會覆寫它,也不會新增第二個標準程式庫。
如果你完全不需要標準程式庫,可以在 gradle.properties 檔案中新增以下 Gradle 屬性:
kotlin.stdlib.default.dependency=false傳遞相依性的版本對齊
從 Kotlin 標準程式庫 1.9.20 版開始,Gradle 會使用標準程式庫中包含的元資料來自動對齊傳遞的 kotlin-stdlib-jdk7 與 kotlin-stdlib-jdk8 相依性。
如果你新增了 1.8.0 至 1.9.10 之間的任何 Kotlin 標準程式庫版本的相依性,例如: implementation("org.jetbrains.kotlin:kotlin-stdlib:1.8.0"),則 Kotlin Gradle 外掛程式會將此 Kotlin 版本用於傳遞的 kotlin-stdlib-jdk7 與 kotlin-stdlib-jdk8 相依性。這避免了來自不同標準程式庫版本的類別重複問題。進一步了解將 kotlin-stdlib-jdk7 與 kotlin-stdlib-jdk8 合併至 kotlin-stdlib。 你可以在 gradle.properties 檔案中使用 kotlin.stdlib.jdk.variants.version.alignment Gradle 屬性來停用此行為:
kotlin.stdlib.jdk.variants.version.alignment=false對齊版本的其他方法
如果你在版本對齊方面遇到問題,可以透過 Kotlin BOM 對齊所有版本。 在你的建置指令碼中宣告對
kotlin-bom的平台相依性:kotlinimplementation(platform("org.jetbrains.kotlin:kotlin-bom:2.4.21"))groovyimplementation platform('org.jetbrains.kotlin:kotlin-bom:2.4.21')如果你沒有新增標準程式庫版本的相依性,但有兩個不同的相依性以傳遞方式引入了不同舊版的 Kotlin 標準程式庫, 則你可以明確要求這些傳遞程式庫使用
2.4.21版本:kotlindependencies { constraints { add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") { version { require("2.4.21") } } add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") { version { require("2.4.21") } } } }groovydependencies { constraints { add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") { version { require("2.4.21") } } add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") { version { require("2.4.21") } } } }如果你新增了 Kotlin 標準程式庫版本
2.4.21的相依性:implementation("org.jetbrains.kotlin:kotlin-stdlib:2.4.21"), 但使用的是舊版(早於1.8.0)的 Kotlin Gradle 外掛程式,請更新 Kotlin Gradle 外掛程式以符合該標準程式庫版本:kotlinplugins { // 將 `<...>` 替換為外掛程式名稱 kotlin("<...>") version "2.4.21" }groovyplugins { // 將 `<...>` 替換為外掛程式名稱 id "org.jetbrains.kotlin.<...>" version "2.4.21" }如果你使用的
kotlin-stdlib-jdk7/kotlin-stdlib-jdk8版本早於1.8.0,例如:implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:SOME_OLD_KOTLIN_VERSION"),並且某個相依性傳遞引入了kotlin-stdlib:1.8+, 請將kotlin-stdlib-jdk<7/8>:SOME_OLD_KOTLIN_VERSION替換為kotlin-stdlib-jdk*:2.4.21, 或從引入它的程式庫中排除傳遞的kotlin-stdlib:1.8+:kotlindependencies { implementation("com.example:lib:1.0") { exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib") } }groovydependencies { implementation("com.example:lib:1.0") { exclude group: "org.jetbrains.kotlin", module: "kotlin-stdlib" } }
設定測試程式庫的相依性
kotlin.test API 可用於在所有受支援平台上測試 Kotlin 專案。 將 kotlin-test 相依性新增至 commonTest 原始碼集,這樣 Gradle 外掛程式就可以為每個測試原始碼集推論對應的測試相依性。
Kotlin/Native 目標不需要額外的測試相依性,且 kotlin.test API 實作是內建的。
kotlin {
sourceSets {
commonTest.dependencies {
implementation(kotlin("test")) // 這會自動引入所有平台相依性
}
}
}kotlin {
sourceSets {
commonTest {
dependencies {
implementation kotlin("test") // 這會自動引入所有平台相依性
}
}
}
}你可以對 Kotlin 模組相依性使用簡寫,例如使用 kotlin("test") 代表 "org.jetbrains.kotlin:kotlin-test"。
你也可以在任何共用或平台專屬的原始碼集中使用 kotlin-test 相依性。
kotlin-test 的 JVM 變體
對於 Kotlin/JVM,Gradle 預設使用 JUnit 4。因此,kotlin("test") 相依性會解析為 JUnit 4 的變體,即 kotlin-test-junit。
你可以在建置指令碼的測試任務中呼叫 useJUnitPlatform() 或 useTestNG() 來選擇 JUnit 5 或 TestNG。 以下範例適用於 Kotlin Multiplatform 專案:
kotlin {
jvm {
testRuns["test"].executionTask.configure {
useJUnitPlatform()
}
}
sourceSets {
commonTest.dependencies {
implementation(kotlin("test"))
}
}
}kotlin {
jvm {
testRuns["test"].executionTask.configure {
useJUnitPlatform()
}
}
sourceSets {
commonTest {
dependencies {
implementation kotlin("test")
}
}
}
}以下範例適用於 JVM 專案:
dependencies {
testImplementation(kotlin("test"))
}
tasks {
test {
useTestNG()
}
}dependencies {
testImplementation 'org.jetbrains.kotlin:kotlin-test'
}
test {
useTestNG()
}自動 JVM 變體解析有時可能會導致設定出現問題。在這種情況下,你可以明確指定所需的架構, 並透過在專案的 gradle.properties 檔案中新增此行來停用自動解析:
kotlin.test.infer.jvm.variant=false如果你在建置指令碼中明確使用了 kotlin("test") 的某個變體,且專案建置因相容性衝突而停止運作, 請參閱相容性指南中的此問題。
設定 kotlinx 程式庫的相依性
如果你使用多平台程式庫並且需要相依於共用程式碼,請僅在共用原始碼集中設定一次該相依性。 使用該程式庫的基本構件名稱,例如 kotlinx-coroutines-core 或 ktor-client-core:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}
}
}kotlin {
sourceSets {
commonMain {
dependencies {
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
}
}
}
}如果你需要平台專屬相依性的 kotlinx 程式庫,仍可在對應的平台原始碼集中使用該程式庫的基本構件名稱:
kotlin {
sourceSets {
jvmMain.dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
}
}
}kotlin {
sourceSets {
jvmMain {
dependencies {
implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
}
}
}
}宣告存儲庫
你可以宣告公開可用的存儲庫以使用其開源相依性。在 repositories{} 區塊中設定存儲庫名稱:
repositories {
mavenCentral()
}repositories {
mavenCentral()
}常見的存儲庫包括 Maven Central 與 Google 的 Maven 存儲庫。
如果你也從事 Maven 專案,我們建議避免將 mavenLocal() 新增為存儲庫,因為在 Gradle 和 Maven 專案之間切換時可能會遇到問題。 如果必須新增 mavenLocal() 存儲庫,請將其新增為 repositories{} 區塊中的最後一個存儲庫。如需詳細資訊,請參閱 The case for mavenLocal()。
如果你需要在多個子專案中宣告相同的存儲庫,請在 settings.gradle(.kts) 檔案的 dependencyResolutionManagement{} 區塊中集中宣告這些存儲庫:
dependencyResolutionManagement {
repositories {
mavenCentral()
}
}dependencyResolutionManagement {
repositories {
mavenCentral()
}
}在子專案中宣告的任何存儲庫都會覆寫集中宣告的存儲庫。有關如何控制此行為以及可用選項的詳細資訊,請參閱 Gradle 的文件。
註冊產生的原始碼
註冊產生的原始碼有助於 IDE、第三方外掛程式和其他工具區分產生的程式碼與常規原始碼檔案。 這有助於像 IDE 這樣的工具在 UI 中以不同方式醒目提示產生的程式碼,並在匯入專案時觸發產生任務。 使用 KotlinSourceSet 介面來註冊產生的原始碼。
若要註冊包含 Kotlin 檔案的目錄,請在 build.gradle.kts 檔案中使用帶有 SourceDirectorySet 型別的 generatedKotlin 屬性。例如:
val generatorTask = project.tasks.register("generator") {
val outputDirectory = project.layout.projectDirectory.dir("src/main/kotlinGen")
outputs.dir(outputDirectory)
doLast {
outputDirectory.file("generated.kt").asFile.writeText(
// language=kotlin
"""
fun printHello() {
println("hello")
}
""".trimIndent()
)
}
}
kotlin.sourceSets.getByName("main").generatedKotlin.srcDir(generatorTask)此範例建立了一個名為 generator 的新任務,其輸出目錄為 "src/main/kotlinGen"。當任務執行時, doLast {} 任務操作會在輸出目錄中建立一個 generated.kt 檔案。最後,該範例將任務的輸出註冊為產生的原始碼。
如果你正在開發 Gradle 外掛程式,可以使用 allKotlinSources 屬性來存取在 KotlinSourceSet.kotlin 和 KotlinSourceSet.generatedKotlin 屬性中註冊的所有原始碼。
後續步驟
進一步了解:
