Kotlin使用Gradle

爲了用 Gradle 構建 Kotlin，你應該設置好 kotlin-gradle 插件，將其應用到你的項目中，並且添加 kotlin-stdlib 依賴。這些操作也可以在 IntelliJ IDEA 中通過調用 Project action 中的 Tools | Kotlin | Configure Kotlin 自動執行。

插件和版本

使用 kotlin-gradle-plugin 編譯 Kotlin 源代碼和模塊.

要使用的 Kotlin 版本通常定義爲 kotlin_version 屬性：

buildscript {
    ext.kotlin_version = '＜要使用的版本＞'

    repositories {
        mavenCentral()
    }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

當通過 Gradle 插件 DSL 使用 Kotlin Gradle 插件 1.1.1 及以上版本時，這不是必需的。

針對 JVM

針對 JVM，需要應用 Kotlin 插件：

apply plugin: "kotlin"

或者，從 Kotlin 1.1.1 起，可以使用 Gradle 插件 DSL 來應用該插件：

plugins {
    id "org.jetbrains.kotlin.jvm" version "＜要使用的版本＞"
}

在這個塊中的 version 必須是字面值，並且不能從其他構建腳本中應用。

Kotlin 源代碼可以與同一個文件夾或不同文件夾中的 Java 源代碼混用。默認約定是使用不同的文件夾：

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

如果不使用默認約定，那麼應該更新相應的 sourceSets 屬性

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

針對 JavaScript

當針對 JavaScript 時，須應用不同的插件：

apply plugin: "kotlin2js"

這個插件只適用於 Kotlin 文件，因此建議將 Kotlin 和 Java 文件分開(如果是同一項目包含 Java 文件的情況)。與
針對 JVM 一樣，如果不使用默認約定，我們需要使用 sourceSets 來指定源代碼文件夾。

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

除了輸出的 JavaScript 文件，該插件默認會創建一個帶二進制描述符的額外 JS 文件。
如果你是構建其他 Kotlin 模塊可以依賴的可重用庫，那麼該文件是必需的，並且應該與轉換結果一起分發。
其生成由 kotlinOptions.metaInfo 選項控制：

compileKotlin2Js {
    kotlinOptions.metaInfo = true
}

針對 Android

Android 的 Gradle 模型與普通 Gradle 有點不同，所以如果我們要構建一個用 Kotlin 編寫的 Android 項目，我們需要
用 kotlin-android 插件取代 kotlin 插件：

buildscript {
    ext.kotlin_version = '＜要使用的版本＞'

    ……

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}
apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'

不要忘記配置標準庫依賴關係。

Android Studio

如果使用 Android Studio，那麼需要在 android 下添加以下內容：

android {
  ……

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

這讓 Android Studio 知道該 kotlin 目錄是源代碼根目錄，所以當項目模型加載到 IDE 中時，它會被正確識別。或者，你可以將 Kotlin 類放在 Java 源代碼目錄中，該目錄通常位於 src/main/java。

配置依賴

除了上面顯示的 kotlin-gradle-plugin 依賴之外，還需要添加 Kotlin 標準庫的依賴：

repositories {
    mavenCentral()
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib"
}

如果針對 JavaScript，請使用 compile "org.jetbrains.kotlin:kotlin-stdlib-js" 替代之。

如果是針對 JDK 7 或 JDK 8，那麼可以使用擴展版本的 Kotlin 標準庫，其中包含
爲新版 JDK 增加的額外的擴展函數。使用以下依賴之一來取代 kotlin-stdlib
：

compile "org.jetbrains.kotlin:kotlin-stdlib-jre7"
compile "org.jetbrains.kotlin:kotlin-stdlib-jre8"

如果你的項目中使用 Kotlin 反射或者測試設施，你也需要添加相應的依賴：

compile "org.jetbrains.kotlin:kotlin-reflect"
testCompile "org.jetbrains.kotlin:kotlin-test"
testCompile "org.jetbrains.kotlin:kotlin-test-junit"

從 Kotlin 1.1.2 起，使用 org.jetbrains.kotlin group 的依賴項默認使用
從已應用的插件獲得的版本來解析。你可以用完整的依賴關係符號
(如 compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")手動提供其版本。

註解處理

請參見 Kotlin 註解處理工具(kapt)的描述。

增量編譯

Kotlin 支持 Gradle 中可選的增量編譯。
增量編譯跟蹤構建之間源文件的改動，因此只有受這些改動影響的文件纔會被編譯。

從 Kotlin 1.1.1 起，默認啓用增量編譯。

有幾種方法來覆蓋默認設置：

1. 將 kotlin.incremental=true 或者 kotlin.incremental=false 行添加到一個 gradle.properties 或者一個 local.properties 文件中；

2. 將 -Pkotlin.incremental=true 或 -Pkotlin.incremental=false 添加到 gradle 命令行參數。請注意，這樣用法中，該參數必須添加到後續每個子構建，並且任何具有禁用增量編譯的構建將使增量緩存失效。

啓用增量編譯時，應該會在構建日誌中看到以下警告消息：

Using kotlin incremental compilation

請注意，第一次構建不會是增量的。

協程支持

協程支持是 Kotlin 1.1 中的一個實驗性的功能，所以當你在項目中使用協程時，Kotlin 編譯器會報告一個警告。
如果要關閉該警告，可以將以下塊添加到你的 build.gradle 文件中：

kotlin {
    experimental {
        coroutines 'enable'
    }
}

編譯器選項

要指定附加的編譯選項，請使用 Kotlin 編譯任務的 kotlinOptions 屬性。

當針對 JVM 時，對於生產代碼這些任務稱爲 compileKotlin 而對於
測試代碼稱爲 compileTestKotlin。對於自定義源文件集(source set)這些任務稱呼取決於 compile＜Name＞Kotlin 模式。

當針對 JavaScript 時，這些任務分別稱爲 compileKotlin2Js 與 compileTestKotlin2Js，以及對於自定義源文件集稱爲 compile＜Name＞Kotlin2Js。

示例：

compileKotlin {
    kotlinOptions.suppressWarnings = true
}

compileKotlin {
    kotlinOptions {
        suppressWarnings = true
    }
}

對於 Gradle 任務的完整選項列表如下：

JVM 和 JS 的公共屬性

名稱

描述

可能的值

默認值

apiVersion

只允許使用來自捆綁庫的指定版本中的聲明

「1.0」、 「1.1」

「1.1」

languageVersion

提供與指定語言版本源代碼兼容性

「1.0」、 「1.1」

「1.1」

suppressWarnings

不生成警告

false

verbose

啓用詳細日誌輸出

false

freeCompilerArgs

附加編譯器參數的列表

[]

JVM 特有的屬性

名稱

描述

可能的值

默認值

javaParameters

爲方法參數生成 Java 1.8 反射的元數據

false

jdkHome

要包含到 classpath 中的 JDK 主目錄路徑，如果與默認 JAVA_HOME 不同的話

jvmTarget

生成的 JVM 字節碼的目標版本(1.6 或 1.8)，默認爲 1.6

「1.6」、 「1.8」

「1.6」

noJdk

不要在 classpath 中包含 Java 運行時

false

noReflect

不要在 classpath 中包含 Kotlin 反射實現

true

noStdlib

不要在 classpath 中包含 Kotlin 運行時

true

JS 特有的屬性

名稱

描述

可能的值

默認值

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

target

生成指定 ECMA 版本的 JS 文件

「v5」

「v5」

生成文檔

要生成 Kotlin 項目的文檔，請使用 Dokka；
相關配置說明請參見 Dokka README
。Dokka 支持混合語言項目，並且可以生成多種格式的輸出
，包括標準 JavaDoc。

OSGi

關於 OSGi 支持請參見 Kotlin OSGi 頁。

示例

以下示例顯示了配置 Gradle 插件的不同可能性：

• Kotlin
• 混用 Java 與 Kotlin
• Android
• JavaScript