Seite bearbeiten
Um ein Kotlin Projekt mit Gradle zu bauen, sollte man das Kotlin Gradle Plugin auf sein Projekt anwenden und Abhängigkeiten konfigurieren.
- Plugin und Versionen
- Mehrere Plattformen anvisieren
- Targeting der JVM
- Kotlin- und Java-Quellen
- Zielgerichtetes JavaScript
- Kotlin- und Java-Quellen
- Targeting Android
- Konfigurieren von Abhängigkeiten
- Abhängigkeitstypen
- Abhängigkeit von der Standardbibliothek
- Abhängigkeiten von Testbibliotheken setzen
- Setzen einer Abhängigkeit von einer kotlinx-Bibliothek
- Abhängigkeiten auf der obersten Ebene festlegen
- Anmerkungsverarbeitung
- Inkrementelle Kompilierung
- Gradle-Build-Cache-Unterstützung
- Gradle-Konfigurationscache-Unterstützung
- Compiler-Optionen
- Attribute, die für JVM, JS, und JS DCE
- Attribute, die für JVM und JS üblich sind
- Attribute spezifisch für JVM
- Attribute speziell für JS
- Generating documentation
- OSGi
- Verwendung von Gradle Kotlin DSL
Plugin und Versionen
Wenden Sie das Kotlin Gradle Plugin an, indem Sie die Gradle Plugins DSL verwenden.
Das Kotlin Gradle Plugin 1.4.30 funktioniert mit Gradle 5.4 und höher. Das kotlin-multiplatformPlugin erfordert Gradle 6.0 oder höher.
plugins { id 'org.jetbrains.kotlin.<...>' version '1.4.30'}plugins { kotlin("<...>") version "1.4.30"}Der Platzhalter <...> sollte durch einen der Plugin-Namen ersetzt werden, die in weiteren Abschnitten zu finden sind.
Mehrere Plattformen anvisieren
Projekte, die mehrere Plattformen anvisieren, sogenannte Multiplattform-Projekte, benötigen das kotlin-multiplatform-Plugin. Erfahren Sie mehr über das Plugin.
Das
kotlin-multiplatform-Plugin funktioniert mit Gradle 6.0 oder höher.
plugins { id 'org.jetbrains.kotlin.multiplatform' version '1.4.30'}plugins { kotlin("multiplatform") version "1.4.30"}Targeting der JVM
Um die JVM anzusteuern, wenden Sie das Kotlin JVM Plugin an.
plugins { id "org.jetbrains.kotlin.jvm" version "1.4.30"}plugins { kotlin("jvm") version "1.4.30"}Das version sollte in diesem Block wörtlich sein und kann nicht von einem anderen Build-Skript angewendet werden.
Alternativ kann man den älteren apply plugin Ansatz verwenden:
apply plugin: 'kotlin'Es wird nicht empfohlen, Kotlin-Plugins mit apply in Gradle Kotlin DSL anzuwenden – siehe warum.
Kotlin- und Java-Quellen
Kotlin-Quellen können zusammen mit Java-Quellen im selben Ordner oder in verschiedenen Ordnern abgelegt werden. Die Standardkonvention ist die Verwendung unterschiedlicher Ordner:
project - src - main (root) - kotlin - javaDie entsprechende sourceSets-Eigenschaft sollte aktualisiert werden, wenn nicht die Standardkonvention verwendet wird:
sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' main.java.srcDirs += 'src/main/myJava'}sourceSets.main { java.srcDirs("src/main/myJava", "src/main/myKotlin")}Zielgerichtetes JavaScript
Wenn Sie nur JavaScript anvisieren, verwenden Sie das kotlin-js-Plugin. Weitere Informationen
plugins { id 'org.jetbrains.kotlin.js' version '1.4.30'}plugins { kotlin("js") version "1.4.30"}Kotlin- und Java-Quellen
Dieses Plugin funktioniert nur für Kotlin-Dateien, daher wird empfohlen, Kotlin- und Java-Dateien getrennt aufzubewahren (falls das Projekt Java-Dateien enthält). Wenn Sie sie nicht getrennt aufbewahren, geben Sie den Quellordner im sourceSets-Block an:
kotlin { sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' }}kotlin { sourceSets.apply { kotlin.srcDir("src/main/myKotlin") }}Targeting Android
Es wird empfohlen, dass Sie Android Studio für die Erstellung von Android-Anwendungen verwenden. Erfahren Sie, wie Sie das Android Gradle Plugin verwenden.
Konfigurieren von Abhängigkeiten
Um eine Abhängigkeit von einer Bibliothek hinzuzufügen, setzen Sie die Abhängigkeit des erforderlichen Typs (z.B. implementation) im dependenciesBlock der Source Sets DSL.
kotlin { sourceSets { commonMain { dependencies { implementation 'com.example:my-library:1.0' } } }}kotlin { sourceSets { val commonMain by getting { dependencies { implementation("com.example:my-library:1.0") } } }}Alternativ können Sie Abhängigkeiten auf der obersten Ebene festlegen.
Abhängigkeitstypen
Wählen Sie den Abhängigkeitstyp entsprechend Ihren Anforderungen.
| Typ | Beschreibung | Wann zu verwenden |
|---|---|---|
api |
Wird sowohl während der Kompilierung als auch zur Laufzeit verwendet und wird an Bibliothekskonsumenten exportiert. | Wenn ein Typ aus einer Abhängigkeit in der öffentlichen API des aktuellen Moduls verwendet wird, verwenden Sie eine api-Abhängigkeit. |
implementation |
Wird während der Kompilierung und zur Laufzeit für das aktuelle Modul verwendet, ist aber für die Kompilierung anderer Module, die von dem mit der `Implementierungs`-Abhängigkeit abhängen, nicht offengelegt. |
Verwenden Sie für Abhängigkeiten, die für die interne Logik eines Moduls benötigt werden. Wenn ein Modul eine Endpunktanwendung ist, die nicht veröffentlicht wird, verwenden Sie |
compileOnly |
Wird für die Kompilierung des aktuellen Moduls verwendet und ist weder zur Laufzeit noch während der Kompilierung anderer Module verfügbar. | Verwenden Sie für APIs, die eine zur Laufzeit verfügbare Implementierung eines Drittanbieters haben. |
runtimeOnly |
Zur Laufzeit verfügbar, aber während der Kompilierung eines Moduls nicht sichtbar. |
Abhängigkeit von der Standardbibliothek
Eine Abhängigkeit von einer Standardbibliothek (stdlib) wird in jedem Quellsatz automatisch hinzugefügt. Die Version der Standardbibliothek entspricht der Version des Kotlin-Gradle-Plugins.
Für plattformspezifische Quellensätze wird die entsprechende plattformspezifische Variante der Bibliothek verwendet, während für den Rest eine allgemeine Standardbibliothek hinzugefügt wird. Das Kotlin-Gradle-Plugin wählt die entsprechende JVM-Standardbibliothek in Abhängigkeit von der kotlinOptions.jvmTarget Compiler-Option des Gradle-Build-Skripts aus.
Wenn Sie eine Standardbibliotheksabhängigkeit explizit deklarieren (zum Beispiel, wenn Sie eine andere Version benötigen), wird das Kotlin-Gradle-Plugin diese nicht überschreiben oder eine zweite Standardbibliothek hinzufügen.
Wenn Sie eine Standardbibliothek überhaupt nicht benötigen, können Sie das Opt-Out-Flag zum gradle.properties hinzufügen:
kotlin.stdlib.default.dependency=falseAbhängigkeiten von Testbibliotheken setzen
Die kotlin.testAPI ist für das Testen verschiedener Kotlin-Projekte verfügbar.
Fügen Sie die entsprechenden Abhängigkeiten zu Testbibliotheken hinzu:
- Für
commonTestfügen Sie die Abhängigkeitenkotlin-test-commonundkotlin-test-annotations-commonhinzu. - Für JVM-Ziele verwenden Sie
kotlin-test-junitoderkotlin-test-testngfür die entsprechende Asserter-Implementierung und das Annotations-Mapping. - Für Kotlin/JS-Ziele fügen Sie
kotlin-test-jsals Testabhängigkeit hinzu.
Kotlin/Native-Ziele erfordern keine zusätzlichen Testabhängigkeiten, und die kotlin.test API-Implementierungen sind eingebaut.
Sie können eine Abkürzung für eine Abhängigkeit von einem Kotlin-Modul verwenden, zum Beispiel kotlin(„test“) für „org.jetbrains.kotlin:kotlin-test“.
Setzen einer Abhängigkeit von einer kotlinx-Bibliothek
Wenn Sie eine kotlinx-Bibliothek verwenden und eine plattformspezifische Abhängigkeit benötigen, können Sie plattformspezifische Varianten von Bibliotheken mit Suffixen wie -jvm oder -js verwenden, zum Beispiel kotlinx-coroutines-core-jvm. Sie können stattdessen auch den Namen des Basisartefakts der Bibliothek verwenden – kotlinx-coroutines-core.
kotlin { sourceSets { jvmMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.2' } } }}Wenn Sie eine Multiplattform-Bibliothek verwenden und vom gemeinsam genutzten Code abhängig sein müssen, setzen Sie die Abhängigkeit nur einmal im gemeinsam genutzten Quellsatz. Verwenden Sie den Namen des Basisartefakts der Bibliothek, z. B. kotlinx-coroutines-core oder ktor-client-core.
kotlin { sourceSets { commonMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.2' } } }}Abhängigkeiten auf der obersten Ebene festlegen
Alternativ können Sie die Abhängigkeiten auf der obersten Ebene mit den Konfigurationsnamen nach dem Muster <sourceSetName><DependencyType> angeben. Dies ist hilfreich für einige in Gradle eingebaute Abhängigkeiten, wie gradleApi(), localGroovy() oder gradleTestKit(), die nicht in der Source Sets Dependency DSL verfügbar sind.
dependencies { commonMainImplementation 'com.example:my-library:1.0'}dependencies { "commonMainImplementation"("com.example:my-library:1.0")}Anmerkungsverarbeitung
Kotlin unterstützt die Verarbeitung von Anmerkungen über das Kotlin Annotation Processing Tool kapt.
Inkrementelle Kompilierung
Das Kotlin Gradle Plugin unterstützt inkrementelle Kompilierung. Die inkrementelle Kompilierung verfolgt Änderungen an Quelldateien zwischen Builds, so dass nur die Dateien kompiliert werden, die von diesen Änderungen betroffen sind.
Die inkrementelle Kompilierung wird für Kotlin/JVM- und Kotlin/JS-Projekte unterstützt und ist seit Kotlin 1.1.1 standardmäßig aktiviert.
Es gibt mehrere Möglichkeiten, die Einstellung zu deaktivieren:
- Fügen Sie die folgende Zeile in die Datei
gradle.propertiesoderlocal.propertiesein:-
kotlin.incremental=falsefür Kotlin/JVM -
kotlin.incremental.js=falsefür Kotlin/JS-Projekte
-
-
Als Befehlszeilenparameter wird
-Pkotlin.incremental=falseoder-Pkotlin.incremental.js=falseverwendet.Beachten Sie, dass in diesem Fall der Parameter zu jedem nachfolgenden Build hinzugefügt werden sollte, und dass jeder Build mit deaktivierter inkrementeller Kompilierung die inkrementellen Caches ungültig macht.
Beachten Sie, dass der erste Build in jedem Fall nicht inkrementell ist.
Gradle-Build-Cache-Unterstützung
Das Kotlin-Plugin unterstützt den Gradle-Build-Cache, der die Build-Ausgaben zur Wiederverwendung in zukünftigen Builds speichert.
Um das Caching für alle Kotlin-Aufgaben zu deaktivieren, setzen Sie das Systemeigenschafts-Flag kotlin.caching.enabled auf false (führen Sie den Build mit dem Argument -Dkotlin.caching.enabled=false aus).
Wenn Sie Kapt verwenden, beachten Sie, dass die Kapt-Annotation-Verarbeitungsaufgaben standardmäßig nicht gecacht werden. Sie können jedoch das Caching für sie manuell aktivieren.
Gradle-Konfigurationscache-Unterstützung
Der Konfigurationscache ist in Gradle 6.5 und später als experimentelles Feature verfügbar. Sie können auf der Gradle-Releases-Seite nachsehen, ob er in den Stable-Status befördert wurde.
Das Kotlin-Plugin unterstützt den Gradle-Konfigurations-Cache, der den Build-Prozess durch die Wiederverwendung der Ergebnisse der Konfigurationsphase beschleunigt.
Lesen Sie in der Gradle-Dokumentation nach, wie Sie den Konfigurations-Cache aktivieren. Sobald Sie den Konfigurations-Cache aktiviert haben, wird das Kotlin Gradle Plugin damit beginnen, ihn zu verwenden.
Compiler-Optionen
Um zusätzliche Kompilierungsoptionen festzulegen, verwenden Sie die kotlinOptions-Eigenschaft einer Kotlin-Kompilierungsaufgabe.
Wenn Sie auf die JVM zielen, heißen die Aufgaben compileKotlin für Produktionscode und compileTestKotlinfür Testcode. Die Tasks für benutzerdefinierte Quellcodesätze werden entsprechend dem Muster compile<Name>Kotlin aufgerufen.
Die Namen der Tasks in Android-Projekten enthalten die Namen der Build-Varianten und folgen dem Muster compile<BuildVariant>Kotlin, z. B. compileDebugKotlin, compileReleaseUnitTestKotlin.
Wenn sie auf JavaScript abzielen, heißen die Tasks compileKotlinJs bzw. compileTestKotlinJs und compile<Name>KotlinJs für benutzerdefinierte Quellcodesätze.
Um eine einzelne Task zu konfigurieren, verwenden Sie ihren Namen. Beispiele:
compileKotlin { kotlinOptions.suppressWarnings = true}//orcompileKotlin { kotlinOptions { suppressWarnings = true }}Beachten Sie, dass Sie bei Gradle Kotlin DSL die Aufgabe zuerst aus dem tasks des Projekts holen sollten.
Verwenden Sie entsprechend die Typen Kotlin2JsCompile und KotlinCompileCommon für die JS- und Common-Ziele.
Es ist auch möglich, alle Kotlin-Kompilierungsaufgaben im Projekt zu konfigurieren:
tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { kotlinOptions { /*...*/ }}tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach { kotlinOptions { /*...*/ }}Die vollständige Liste der Optionen für die Gradle-Aufgaben ist die folgende:
Attribute, die für JVM, JS, und JS DCE
| Name | Beschreibung | Mögliche Werte | Standardwert | |
|---|---|---|---|---|
allWarningsAsErrors |
Melde einen Fehler, wenn es irgendwelche Warnungen | falsch | ||
suppressWarnings |
Keine Warnungen erzeugen | falsch | ||
verbose |
Aktivieren der ausführlichen Protokollierungsausgabe | false | ||
freeCompilerArgs |
Eine Liste zusätzlicher Compiler-Argumente |
Attribute, die für JVM und JS üblich sind
Attribute spezifisch für JVM
| Name | Beschreibung | Mögliche Werte | Standardwert |
|---|---|---|---|
javaParameters |
Erzeugen von Metadaten für Java 1.8 Reflexion auf Methodenparameter | false | |
jdkHome |
Ein benutzerdefiniertes JDK vom angegebenen Ort in den Klassenpfad anstelle des standardmäßigen JAVA_HOME | ||
jvmTarget |
Zielversion des generierten JVM Bytecodes | „1.6“, „1.8“, „9“, „10“, „11“, „12“, „13“, „14“, „15“ | „1.6“ |
noJdk |
Die Java-Laufzeit nicht automatisch in den Klassenpfad aufnehmen | false | |
noReflect |
Die Kotlin-Reflection nicht automatisch in den Klassenpfad | wahr | |
noStdlib |
Kotlin/JVM stdlib und Kotlin reflection nicht automatisch in den Klassenpfad einbinden | wahr | |
useIR |
Das IR-Backend verwenden | falsch |
Attribute speziell für JS
| Name | Beschreibung | Mögliche Werte | Standardwert |
|---|---|---|---|
friendModulesDisabled |
Interner Deklarationsexport deaktivieren | false | |
main |
Definieren, ob die main Funktion bei Ausführung aufgerufen werden soll |
„call“, „noCall“ | „call“ |
metaInfo |
Generate .meta.js und .kjsm Dateien mit Metadaten. Wird verwendet, um eine Bibliothek zu erstellen | true | |
moduleKind |
Die Art des vom Compiler erzeugten JS-Moduls | „umd“, „commonjs“, „amd“, „plain“ | „umd“ |
noStdlib |
Die standardmäßige Kotlin/JS stdlib nicht automatisch in die Kompilierungsabhängigkeiten aufnehmen | true | |
outputFile |
Ziel *.js-Datei für das Kompilierungsergebnis | „<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js“ | |
sourceMap |
Generate source map | true | |
sourceMapEmbedSources |
Embed source files into source map | „never“, „always“, „inlining“ | |
sourceMapPrefix |
Hinzufügen des angegebenen Präfixes zu Pfaden in der Source-Map | ||
target |
Erzeugen von JS-Dateien für bestimmte ECMA-Version | „v5“ | „v5“ |
typedArrays |
Translate primitive arrays to JS typed arrays | true |
Generating documentation
To generate documentation for Kotlin projects, verwenden Sie Dokka;Konfigurationsanweisungen finden Sie in der README von Dokka. Dokka unterstützt gemischtsprachige Projekte und kann Ausgaben in verschiedenen Formaten generieren, einschließlich Standard JavaDoc.
OSGi
Für OSGi Unterstützung siehe die Kotlin OSGi Seite.
Verwendung von Gradle Kotlin DSL
Bei Verwendung von Gradle Kotlin DSL, wenden Sie die Kotlin Plugins mit dem plugins { ... } Block an. Wenn Sie sie stattdessen mit apply { plugin(...) } anwenden, kann es zu nicht aufgelösten Referenzen auf die von Gradle Kotlin DSL generierten Erweiterungen kommen. Um dies zu beheben, können Sie die fehlerhaften Verwendungen auskommentieren, die Gradle-Aufgabe kotlinDslAccessorsSnapshot ausführen, dann die Verwendungen zurückkommentieren und den Build erneut ausführen oder das Projekt erneut in die IDE importieren.