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

# 使用 Maven [TOC] ## 插件與版本 *kotlin-maven-plugin* 用于編譯 Kotlin 源代碼與模塊，目前只支持 Maven V3。通過 *kotlin.version* 屬性定義要使用的 Kotlin 版本： ```xml <properties> <kotlin.version>{{ site.data.releases.latest.version }}</kotlin.version> </properties> ``` ## 依賴 Kotlin 有一個廣泛的標準庫可用于應用程序。在 pom 文件中配置以下依賴關系： ```xml <dependencies> <dependency> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-stdlib</artifactId> <version>${kotlin.version}</version> </dependency> </dependencies> ``` 如果是面向 JDK 7 或 JDK 8，那么可以使用擴展版本的 Kotlin 標準庫，其中包含為新版 JDK 所增 API 而加的額外的擴展函數。使用 `kotlin-stdlib-jdk7`或 `kotlin-stdlib-jdk8` 取代 `kotlin-stdlib`，這取決于你的 JDK 版本（對于 Kotlin 1.1.x 用 `kotlin-stdlib-jre7` 與 `kotlin-stdlib-jre8`，因為相應的 `jdk` 構件在 1.2.0 才引入）。如果你的項目使用 [Kotlin 反射](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.reflect.full/index.html) 或者測試設施，那么你還需要添加相應的依賴項。其構件 ID 對于反射庫是 `kotlin-reflect`，對于測試庫是 `kotlin-test` 與 `kotlin-test-junit`。 ## 編譯只有 Kotlin 的源代碼要編譯源代碼，請在 `<build>` 標簽中指定源代碼目錄： ```xml <build> <sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory> <testSourceDirectory>${project.basedir}/src/test/kotlin</testSourceDirectory> </build> ``` 需要引用 Kotlin Maven 插件來編譯源代碼： ```xml <build> <plugins> <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <executions> <execution> <id>compile</id> <goals> <goal>compile</goal> </goals> </execution> <execution> <id>test-compile</id> <goals> <goal>test-compile</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ``` ## 同時編譯 Kotlin 與 Java 源代碼要編譯混合代碼應用程序，必須在 Java 編譯器之前調用 Kotlin 編譯器。按照 maven 的方式，這意味著應該使用以下方法在 maven-compiler-plugin 之前運行 kotlin-maven-plugin，確保 pom.xml 文件中的 kotlin 插件位于 maven-compiler-plugin 上面： ```xml <build> <plugins> <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <executions> <execution> <id>compile</id> <goals> <goal>compile</goal> </goals> <configuration> <sourceDirs> <sourceDir>${project.basedir}/src/main/kotlin</sourceDir> <sourceDir>${project.basedir}/src/main/java</sourceDir> </sourceDirs> </configuration> </execution> <execution> <id>test-compile</id> <goals> <goal>test-compile</goal> </goals> <configuration> <sourceDirs> <sourceDir>${project.basedir}/src/test/kotlin</sourceDir> <sourceDir>${project.basedir}/src/test/java</sourceDir> </sourceDirs> </configuration> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.5.1</version> <executions>  <execution> <id>default-compile</id> <phase>none</phase> </execution>  <execution> <id>default-testCompile</id> <phase>none</phase> </execution> <execution> <id>java-compile</id> <phase>compile</phase> <goals> <goal>compile</goal> </goals> </execution> <execution> <id>java-test-compile</id> <phase>test-compile</phase> <goals> <goal>testCompile</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ``` ## 增量編譯為了使構建更快，可以為 Maven 啟用增量編譯（從 Kotlin 1.1.2 起支持）。為了做到這一點，需要定義 `kotlin.compiler.incremental` 屬性： ```xml <properties> <kotlin.compiler.incremental>true</kotlin.compiler.incremental> </properties> ``` 或者，使用 `-Dkotlin.compiler.incremental=true` 選項運行構建。 ## 注解處理請參見 [Kotlin 注解處理工具](http://www.kotlincn.net/docs/reference/kapt.html)（`kapt`）的描述。 ## 協程支持在 Kotlin 1.2 中[協程](http://www.kotlincn.net/docs/reference/coroutines.html)支持是一項實驗性的特性，因此當你在項目中使用協程時 Kotlin 編譯器會報警告。可以將以下代碼塊添加到 `pom.xml` 文件中來關閉這一警告： ```xml <configuration> <experimentalCoroutines>enable</experimentalCoroutines> </configuration> ``` ## Jar 文件要創建一個僅包含模塊代碼的小型 Jar 文件，請在 Maven pom.xml 文件中的 `build->plugins` 下面包含以下內容，其中 `main.class` 定義為一個屬性，并指向主 Kotlin 或 Java 類： ```xml <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>2.6</version> <configuration> <archive> <manifest> <addClasspath>true</addClasspath> <mainClass>${main.class}</mainClass> </manifest> </archive> </configuration> </plugin> ``` ## 獨立的 Jar 文件要創建一個獨立的（self-contained）Jar 文件，包含模塊中的代碼及其依賴項，請在 Maven pom.xml 文件中的 `build->plugins` 下面包含以下內容其中 `main.class` 定義為一個屬性，并指向主 Kotlin 或 Java 類： ```xml <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-assembly-plugin</artifactId> <version>2.6</version> <executions> <execution> <id>make-assembly</id> <phase>package</phase> <goals> <goal>single</goal> </goals> <configuration> <archive> <manifest> <mainClass>${main.class}</mainClass> </manifest> </archive> <descriptorRefs> <descriptorRef>jar-with-dependencies</descriptorRef> </descriptorRefs> </configuration> </execution> </executions> </plugin> ``` 這個獨立的 jar 文件可以直接傳給 JRE 來運行應用程序： ``` bash java -jar target/mymodule-0.0.1-SNAPSHOT-jar-with-dependencies.jar ``` ## 面向 JavaScript 為了編譯 JavaScript 代碼，需要使用 `js` 和 `test-js` 目標來執行 `compile`： ```xml <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <executions> <execution> <id>compile</id> <phase>compile</phase> <goals> <goal>js</goal> </goals> </execution> <execution> <id>test-compile</id> <phase>test-compile</phase> <goals> <goal>test-js</goal> </goals> </execution> </executions> </plugin> ``` 你還需要更改標準庫依賴： ```xml <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-stdlib-js</artifactId> <version>${kotlin.version}</version> ``` 對于單元測試支持，你還需要添加對 `kotlin-test-js` 構件的依賴。更多信息請參閱[以 Maven 入門使用 Kotlin 與 JavaScript](https://www.kotlincn.net/docs/tutorials/javascript/getting-started-maven/getting-started-with-maven.html) 教程。 ## 指定編譯器選項可以將額外的編譯器選項與參數指定為 Maven 插件節點的 `<configuration>` 元素下的標簽： ```xml <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <executions>……</executions> <configuration> <nowarn>true</nowarn>  <args> <arg>-Xjsr305=strict</arg>  ... </args> </configuration> </plugin> ``` 許多選項還可以通過屬性來配置： ```xml <project ……> <properties> <kotlin.compiler.languageVersion>1.0</kotlin.compiler.languageVersion> </properties> </project> ``` 支持以下屬性： ### JVM 和 JS 的公共屬性 | 名稱 | 屬性名 | 描述 | 可能的值 | 默認值 | |------|---------------|-------------|-----------------|--------------| | nowarn | | 不生成警告 | true、 false | false | | languageVersion | kotlin.compiler.languageVersion | 提供與指定語言版本源代碼兼容性 | "1.0"、 "1.1"、 "1.2"、"1.3"、 "1.4 (EXPERIMENTAL)" | | apiVersion | kotlin.compiler.apiVersion | 只允許使用來自捆綁庫的指定版本中的聲明 | "1.0"、 "1.1"、 "1.2"、"1.3"、 "1.4 (EXPERIMENTAL)" | | sourceDirs | | 包含要編譯源文件的目錄 | | 該項目源代碼根目錄 | compilerPlugins | | 啟用[編譯器插件](http://www.kotlincn.net/docs/reference/compiler-plugins.html) | | [] | pluginOptions | | 編譯器插件的選項 | | [] | args | | 額外的編譯器參數 | | [] ### JVM 特有的屬性 | 名稱 | 屬性名 | 描述 | 可能的值 | 默認值 | |------|---------------|-------------|-----------------|--------------| | jvmTarget | kotlin.compiler.jvmTarget | 生成的 JVM 字節碼的目標版本 | "1.6"、 "1.8"、 "9"、 "10"、 "11"、 "12" | "1.6" | | jdkHome | kotlin.compiler.jdkHome | 要包含到 classpath 中的 JDK 主目錄路徑，如果與默認 JAVA_HOME 不同的話 | |   | ### JS 特有的屬性 | 名稱 | 屬性名 | 描述 | 可能的值 | 默認值 | |------|---------------|-------------|-----------------|--------------| | outputFile | | 輸出文件路徑 | | | | metaInfo | | 使用元數據生成 .meta.js 與 .kjsm 文件。用于創建庫 | true、 false | true | sourceMap | | 生成源代碼映射（source map） | true、 false | false | sourceMapEmbedSources | | 將源代碼嵌入到源代碼映射中 | "never"、 "always"、 "inlining" | "inlining" | | sourceMapPrefix | | 源代碼映射中路徑的前綴 | | | | moduleKind | | 編譯器生成的模塊類型 | "plain"、 "amd"、 "commonjs"、 "umd" | "plain" ## 生成文檔標準的 JavaDoc 生成插件（`maven-javadoc-plugin`）不支持 Kotlin 代碼。要生成 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 頁](http://www.kotlincn.net/docs/reference/kotlin-osgi.html)。 ## 示例一個示例 Maven 項目可以[從 Github 版本庫直接下載](https://github.com/JetBrains/kotlin-examples/archive/master/maven.zip)