使用Gradle · Kotin知識點難點歸納總結

# 使用 Gradle [TOC] 為了用 Gradle 構建 Kotlin 項目，需要[設置好 *kotlin-gradle* 插件](http://www.kotlincn.net/docs/reference/using-gradle.html#%E6%8F%92%E4%BB%B6%E4%B8%8E%E7%89%88%E6%9C%AC)，[將其應用](http://www.kotlincn.net/docs/reference/using-gradle.html#%E9%9D%A2%E5%90%91-jvm)到你的項目中，并且[添加 *kotlin-stdlib* 依賴](http://www.kotlincn.net/docs/reference/using-gradle.html#%E9%85%8D%E7%BD%AE%E4%BE%9D%E8%B5%96)。這些操作也可以在 IntelliJ IDEA 中通過調用 **Project action** 中的 **Tools \| Kotlin \| Configure Kotlin** 自動執行。 ## 插件與版本使用 [Gradle 插件 DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block) 應用 Kotlin Gradle 插件。 Kotlin Gradle 插件適用于 Gradle 4.1 及更高版本。 ```groovy //groovy plugins { id 'org.jetbrains.kotlin.＜……＞' version '{{ site.data.releases.latest.version }}' } ``` ```kotlin //kotlin plugins { kotlin("＜……＞") version "{{ site.data.releases.latest.version }}" } ``` 需要將其中的占位符 `＜……＞` 替換為可在后續部分中找到的插件名之一。或者通過將依賴項 `kotlin-gradle-plugin` 添加到構建腳本類路徑來應用插件： ``` groovy //groovy buildscript { repositories { mavenCentral() } dependencies { classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:{{ site.data.releases.latest.version }}" } } plugins { id "org.jetbrains.kotlin.＜……＞" version "{{ site.data.releases.latest.version }}" } ``` ```kotlin //kotlin buildscript { repositories { mavenCentral() } dependencies { classpath(kotlin("gradle-plugin", version = "{{ site.data.releases.latest.version }}")) } } plugins { kotlin("＜……＞") } ``` 當通過 [Gradle 插件 DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block) 與 [Gradle Kotlin DSL](https://github.com/gradle/kotlin-dsl) 使用 Kotlin Gradle 插件 1.1.1 及以上版本時，這不是必需的。 ## 構建 Kotlin 多平臺項目使用 `kotlin-multiplatform` 插件構建[多平臺項目](http://www.kotlincn.net/docs/reference/multiplatform.html)在[以 Gradle 構建多平臺項目](http://www.kotlincn.net/docs/reference/building-mpp-with-gradle.html)中詳述。 ## 面向 JVM 如需面向 JVM 平臺，請應用 Kotlin JVM 插件。自 Kotlin 1.1.1 起，可以使用 [Gradle 插件 DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block) 來應用該插件： ```groovy //groovy plugins { id "org.jetbrains.kotlin.jvm" version "{{ site.data.releases.latest.version }}" } ``` ```kotlin //kotlin plugins { kotlin("jvm") version "{{ site.data.releases.latest.version }}" } ``` 在這個代碼塊中的 `version` 應該是字面值，并且不能在其他構建腳本中應用。或者使用舊版 `apply plugin` 方式： ```groovy //groovy apply plugin: 'kotlin' ``` 不建議在 Gradle Kotlin DSL 中以 `apply` 的方式應用 Kotlin 插件。詳見[下文](http://www.kotlincn.net/docs/reference/using-gradle.html#%E4%BD%BF%E7%94%A8-gradle-kotlin-dsl)。 Kotlin 源代碼可以與同一個文件夾或不同文件夾中的 Java 源代碼混用。默認約定是使用不同的文件夾： ```groovy project - src - main (root) - kotlin - java ``` 如果不使用默認約定，那么應該更新相應的 *sourceSets* 屬性： ```groovy //groovy sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' main.java.srcDirs += 'src/main/myJava' } ``` ```kotlin sourceSets["main"].java.srcDir("src/main/myJava") sourceSets["main"].withConvention(KotlinSourceSet::class) { kotlin.srcDir("src/main/myKotlin") } ``` 對于 Gradle Kotlin DSL，請改用 `java.sourceSets { …… }` 配置源集。 ## 面向 JavaScript 當面向 JavaScript 時，須應用不同的插件： ``` groovy plugins { id 'org.jetbrains.kotlin.js' version '{{ site.data.releases.latest.version }}' } ``` ```kotlin plugins { kotlin("js") version "{{ site.data.releases.latest.version }}" } ``` 這個插件只適用于 Kotlin 文件，因此建議將 Kotlin 和 Java 文件分開（如果是同一項目包含 Java 文件的情況）。與面向 JVM 一樣，如果不使用默認約定，需要使用 *sourceSets* 來指定源代碼文件夾： ```groovy sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' } ``` ```kotlin sourceSets["main"].withConvention(KotlinSourceSet::class) { kotlin.srcDir("src/main/myKotlin") } ``` 除了輸出的 JavaScript 文件，該插件默認會創建一個帶二進制描述符的額外 JS 文件。如果你是構建其他 Kotlin 模塊可以依賴的可重用庫，那么該文件是必需的，并且應該與轉換結果一起分發。其生成由 `kotlinOptions.metaInfo` 選項控制： ```groovy compileKotlin2Js { kotlinOptions.metaInfo = true } ``` ```kotlin tasks { "compileKotlin2Js"(Kotlin2JsCompile::class) { kotlinOptions.metaInfo = true } } ``` ## 面向 Android Android 的 Gradle 模型與普通 Gradle 有點不同，所以如果我們要構建一個用 Kotlin 編寫的 Android 項目，我們需要用 *kotlin-android* 插件取代 *kotlin* 插件： ```groovy buildscript { ext.kotlin_version = '{{ site.data.releases.latest.version }}' …… dependencies { classpath 'com.android.tools.build:gradle:3.2.1' classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" } } plugins { id 'com.android.application' id 'kotlin-android' } ``` ```kotlin buildscript { dependencies { classpath("com.android.tools.build:gradle:3.2.1") classpath(kotlin("gradle-plugin", version = "{{ site.data.releases.latest.version }}")) } } plugins { id("com.android.application") id("kotlin-android") } ``` Kotlin Gradle 插件適用于 Android Gradle 插件 3.0 及更高版本。不要忘記配置[標準庫依賴關系](http://www.kotlincn.net/docs/reference/using-gradle.html#%E9%85%8D%E7%BD%AE%E4%BE%9D%E8%B5%96)。 ### Android Studio 如果使用 Android Studio，那么需要在 android 下添加以下內容： ```groovy android { …… sourceSets { main.java.srcDirs += 'src/main/kotlin' } } ``` ```kotlin android { …… sourceSets["main"].java.srcDir("src/main/kotlin") } ``` 這讓 Android Studio 知道該 kotlin 目錄是源代碼根目錄，所以當項目模型加載到 IDE 中時，它會被正確識別。或者，你可以將 Kotlin 類放在 Java 源代碼目錄中，該目錄通常位于 `src/main/java`。 ## 配置依賴除了上面顯示的 `kotlin-gradle-plugin` 依賴之外，還需要添加 Kotlin 標準庫的依賴： ```groovy repositories { mavenCentral() } dependencies { implementation "org.jetbrains.kotlin:kotlin-stdlib" } ``` ```kotlin repositories { mavenCentral() } dependencies { implementation(kotlin("stdlib")) } ``` Kotlin 標準庫 `kotlin-stdlib` 面向 Java 6 及以上版本。還有擴展版本的標準庫，增加了對 JDK 7 與 JDK 8 中某些特性支持。如需使用這些版本，請添加下列依賴之一而不是 `kotlin-stdlib`： ```groovy implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7" implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8" ``` ```kotlin implementation(kotlin("stdlib-jdk7")) implementation(kotlin("stdlib-jdk8")) ``` 在 Kotlin 1.1.x 中，請使用 `kotlin-stdlib-jre7` 與 `kotlin-stdlib-jre8`。如果是面向 JavaScript，請使用依賴項 `stdlib-js` 。 ```groovy implementation "org.jetbrains.kotlin:kotlin-stdlib-js" ``` ```kotlin implementation(kotlin("stdlib-js")) ``` 如果項目中用到了 [Kotlin 反射](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.reflect.full/index.html)或者測試設施，還需要添加相應的依賴項： ```groovy implementation "org.jetbrains.kotlin:kotlin-reflect" testImplementation "org.jetbrains.kotlin:kotlin-test" testImplementation "org.jetbrains.kotlin:kotlin-test-junit" ``` ```kotlin implementation(kotlin("reflect")) testImplementation(kotlin("test")) testImplementation(kotlin("test-junit")) ``` 自 Kotlin 1.1.2 起，使用 `org.jetbrains.kotlin` group 的依賴項默認使用從已應用的插件獲得的版本來解析。你可以用完整的依賴關系助記符： ```groovy implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" ``` ```kotlin implementation(kotlin("stdlib", kotlinVersion)) ``` ## 注解處理 Kotlin 通過 *Kotlin 注解處理工具*（`kapt`）支持注解處理。kapt 同 Gradle 合用的用法已在 [kapt 頁](kapt.html)描述。 ## 增量編譯 Kotlin Gradle 插件支持支持增量編譯。增量編譯會跟蹤多次構建之間源文件的變更，因此只會編譯這些變更所影響的文件。 Kotlin/JVM 與 Kotlin/JS 項目均支持增量編譯。對于 Kotlin 1.1.1 起的 Kotlin/JVM 項目以及自 Kotlin 1.3.20 起的 Kotlin/JS 項目默認啟用增量編譯。有幾種方法可以覆蓋默認設置： * 在 Gradle 配置文件中：在 `gradle.properties` 或者 `local.properties` 中，對于 Kotlin/JVM 項目添加一行 `kotlin.incremental=＜值＞`，對于 Kotlin/JS 項目添加一行 `kotlin.incremental.js=＜值＞`。`＜值＞` 是一個反應增量編譯用法的布爾值。 * 在 Gradle 命令行參數中：添加帶有反應增量編譯用法的布爾值的 `-Pkotlin.incremental` or `-Pkotlin.incremental.js` 參數。請注意，這樣用法中，該參數必須添加到后續每個子構建，并且任何具有禁用增量編譯的構建將使增量緩存失效。請注意，任何情況下首次構建都不會是增量的。 ## Gradle 構建緩存支持（自 1.2.20 起） Kotlin 插件支持 [Gradle 構建緩存](https://guides.gradle.org/using-build-cache/)（需要 Gradle 4.3 及以上版本；低版本則禁用緩存）。如需禁用所有 Kotlin 任務的緩存，請將系統屬性標志 `kotlin.caching.enabled` 設置為 `false`（運行構建帶上參數 `-Dkotlin.caching.enabled=false`）。如果使用 [kapt](kapt.html)，請注意默認情況下不會緩存注解處理任務。不過，可以手動為它們啟用緩存。詳見 [kapt 頁](kapt.html#gradle-構建緩存支持自-1220-起)。 ## 編譯器選項要指定附加的編譯選項，請使用 Kotlin 編譯任務的 `kotlinOptions` 屬性。當面向 JVM 時，對于生產代碼這些任務稱為 `compileKotlin` 而對于測試代碼稱為 `compileTestKotlin`。對于自定義源文件集（source set）這些任務稱呼取決于 `compile＜Name＞Kotlin` 模式。 Android 項目中的任務名稱包含[構建變體](https://developer.android.com/studio/build/build-variants.html) 名稱，并遵循 `compile<BuildVariant>Kotlin` 的模式，例如 `compileDebugKotlin`、 `compileReleaseUnitTestKotlin`。當面向 JavaScript 時，這些任務分別稱為 `compileKotlin2Js` 與 `compileTestKotlin2Js`，以及對于自定義源文件集稱為 `compile＜Name＞Kotlin2Js`。要配置單個任務，請使用其名稱。示例： ```groovy compileKotlin { kotlinOptions.suppressWarnings = true } //或者 compileKotlin { kotlinOptions { suppressWarnings = true } } ``` ```kotlin import org.jetbrains.kotlin.gradle.tasks.KotlinCompile // …… val compileKotlin: KotlinCompile by tasks compileKotlin.kotlinOptions.suppressWarnings = true ``` 請注意，對于 Gradle Kotlin DSL，首先從項目的 `tasks` 中獲取任務。相應地，為 JS 與 Common 目標使用類型 `Kotlin2JsCompile` 與 `KotlinCompileCommon`。也可以在項目中配置所有 Kotlin 編譯任務： ```groovy tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all { kotlinOptions { …… } } ``` ```kotlin import org.jetbrains.kotlin.gradle.tasks.KotlinCompile tasks.withType<KotlinCompile> { kotlinOptions.suppressWarnings = true } ``` 對于 Gradle 任務的完整選項列表如下： ### JVM、JS 與 JS DCE 的公共屬性 | 名稱 | 描述 | 可能的值 |默認值 | |------|-------------|-----------------|--------------| | `allWarningsAsErrors` | 任何警告都報告為錯誤 | | false | | `suppressWarnings` | 不生成警告 | | false | | `verbose` | 啟用詳細日志輸出 | | false | | `freeCompilerArgs` | 附加編譯器參數的列表 | | [] | ### JVM 與 JS 的公共屬性 | Name | Description | Possible values |Default value | |------|-------------|-----------------|--------------| | `apiVersion` | 只允許使用來自捆綁庫的指定版本中的聲明 | "1.0"、 "1.1"、 "1.2"、 "1.3"、 "1.4 (EXPERIMENTAL)" | | | `languageVersion` | 提供與指定語言版本源代碼兼容性 | "1.0"、 "1.1"、 "1.2"、 "1.3"、 "1.4 (EXPERIMENTAL)" | | ### JVM 特有的屬性 | 名稱 | 描述 | 可能的值 |默認值 | |------|-------------|-----------------|--------------| | `javaParameters` | 為方法參數生成 Java 1.8 反射的元數據 | | false | | `jdkHome` | 要包含到 classpath 中的 JDK 主目錄路徑，如果與默認 JAVA_HOME 不同的話 | | | | `jvmTarget` | 生成的 JVM 字節碼的目標版本（1.6、 1.8、 9、 10、 11 或 12），默認為 1.6 | "1.6"、 "1.8"、 "9"、 "10"、 "11"、 "12" | "1.6" | | `noJdk` | 不要在 classpath 中包含 Java 運行時 | | false | | `noReflect` | 不要在 classpath 中包含 Kotlin 反射實現 | | true | | `noStdlib` | 不要在 classpath 中包含 Kotlin 運行時 | | true | ### JS 特有的屬性 | 名稱 | 描述 | 可能的值 |默認值 | |------|-------------|-----------------|--------------| | `friendModulesDisabled` | 禁用內部聲明導出 | | false | | `main` | 是否要調用 main 函數 | "call"、 "noCall" | "call" | | `metaInfo` | 使用元數據生成 .meta.js 與 .kjsm 文件。用于創建庫 | | true | | `moduleKind` | 編譯器生成的模塊類型 | "plain"、 "amd"、 "commonjs"、 "umd" | "plain" | | `noStdlib` | 不使用捆綁的 Kotlin stdlib | | true | | `outputFile` | 輸出文件路徑 | | | | `sourceMap` | 生成源代碼映射（source map） | | false | | `sourceMapEmbedSources` | 將源代碼嵌入到源代碼映射中 | "never"、 "always"、 "inlining" | | | `sourceMapPrefix` | 源代碼映射中路徑的前綴 | | | | `target` | 生成指定 ECMA 版本的 JS 文件 | "v5" | "v5" | | `typedArrays` | 將原生數組轉換為 JS 帶類型數組 | | true | ## 生成文檔要生成 Kotlin 項目的文檔，請使用 [Dokka](https://github.com/Kotlin/dokka)；相關配置說明請參見 [Dokka README](https://github.com/Kotlin/dokka/blob/master/README.md#using-the-maven-plugin)。Dokka 支持混合語言項目，并且可以生成多種格式的輸出，包括標準 JavaDoc。 ## OSGi 關于 OSGi 支持請參見 [Kotlin OSGi 頁](kotlin-osgi.html)。 ## 使用 Gradle Kotlin DSL 使用 [Gradle Kotlin DSL](https://github.com/gradle/kotlin-dsl) 時，請使用 `plugins { …… }` 塊應用 Kotlin 插件。如果使用 `apply { plugin(……) }` 來應用的話，可能會遇到未解析的到由 Gradle Kotlin DSL 所生成擴展的引用問題。為了解決這個問題，可以注釋掉出錯的用法，運行 Gradle 任務 `kotlinDslAccessorsSnapshot`，然后解除該用法注釋并重新運行構建或者重新將項目導入到 IDE 中。 ## 示例以下示例顯示了配置 Gradle 插件的不同可能性： * [Kotlin](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/hello-world) * [混用 Java 與 Kotlin](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/mixed-java-kotlin-hello-world) * [Android](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/android-mixed-java-kotlin-project) * [JavaScript](https://github.com/JetBrains/kotlin/tree/master/libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/resources/testProject/kotlin2JsProject)