Gradle gebruiken - Kotlin programmeertaal

Pagina bewerken

Om een Kotlin project met Gradle te bouwen, moet u de Kotlin Gradle plugin op uw project toepassen en de afhankelijkheden configureren.

Plugin en versies

Toepassen van de Kotlin Gradle plugin door gebruik te maken van de Gradle plugins DSL.

De Kotlin Gradle plugin 1.4.30 werkt met Gradle 5.4 en later. Voor de kotlin-multiplatform plugin is Gradle 6.0 of hoger vereist.

plugins { id 'org.jetbrains.kotlin.<...>' version '1.4.30'}

plugins { kotlin("<...>") version "1.4.30"}

De placeholder <...> moet worden vervangen door een van de plugin-namen die in verdere secties kunnen worden gevonden.

Gericht op meerdere platforms

Projecten die gericht zijn op meerdere platforms, de zogenaamde multiplatformprojecten, vereisen de kotlin-multiplatform-plugin. Meer informatie over deze plugin.

De kotlin-multiplatform plugin werkt met Gradle 6.0 of later.

plugins { id 'org.jetbrains.kotlin.multiplatform' version '1.4.30'}

plugins { kotlin("multiplatform") version "1.4.30"}

Targeting the JVM

Om de JVM te targeten, moet de Kotlin JVM plugin worden toegepast.

plugins { id "org.jetbrains.kotlin.jvm" version "1.4.30"}

plugins { kotlin("jvm") version "1.4.30"}

De version moet letterlijk zijn in dit blok, en het kan niet worden toegepast vanuit een ander build script.

Aternatief kunt u de oudere apply plugin aanpak gebruiken:

apply plugin: 'kotlin'

Het is niet aan te raden om Kotlin plugins toe te passen met apply in Gradle Kotlin DSL – zie waarom.

Kotlin en Java sources

Kotlin sources kunnen samen met Java sources in dezelfde map worden opgeslagen, of in verschillende mappen worden geplaatst. De standaardconventie is het gebruik van verschillende mappen:

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

De corresponderende sourceSets eigenschap moet worden bijgewerkt als niet de standaardconventie wordt gebruikt:

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

sourceSets.main { java.srcDirs("src/main/myJava", "src/main/myKotlin")}

Targeting JavaScript

Wanneer alleen JavaScript wordt getarget, moet de kotlin-js plugin worden gebruikt. Meer informatie

plugins { id 'org.jetbrains.kotlin.js' version '1.4.30'}

plugins { kotlin("js") version "1.4.30"}

Kotlin en Java bronnen

Deze plugin werkt alleen voor Kotlin bestanden, dus het is aan te raden om Kotlin en Java bestanden apart te bewaren (in het geval dat het project Java bestanden bevat). Als u ze niet apart opslaat, geeft u de bronmap op in het sourceSets-blok:

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

kotlin { sourceSets.apply { kotlin.srcDir("src/main/myKotlin") }}

Targeting Android

Het is aanbevolen om Android Studio te gebruiken voor het maken van Android-toepassingen. Leer hoe u de Android Gradle-plugin kunt gebruiken.

Afhankelijkheden configureren

Om een afhankelijkheid van een bibliotheek toe te voegen, stelt u de afhankelijkheid van het vereiste type in (bijvoorbeeld implementation) in het dependencies-blok van de bronverzamelingen 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") } } }}

Aternatief kunt u afhankelijkheden instellen op het topniveau.

Afhankelijkheidstypen

Kies het afhankelijkheidstype op basis van uw vereisten.

Type	Beschrijving	Wanneer te gebruiken
`api`	Gebruikt zowel tijdens het compileren als tijdens runtime en wordt geëxporteerd naar gebruikers van de bibliotheek.	Als een type van een afhankelijkheid wordt gebruikt in de openbare API van de huidige module, gebruikt u een `api`-afhankelijkheid.
`implementation`	Gebruikt tijdens compilatie en runtime voor de huidige module, maar wordt niet blootgesteld voor compilatie van andere modules die afhankelijk zijn van de module met de `implementatie`-afhankelijkheid.	Gebruik deze voor afhankelijkheden die nodig zijn voor de interne logica van een module. Als een module een endpoint-applicatie is die niet wordt gepubliceerd, gebruik dan `implementation`-afhankelijkheden in plaats van `api`-afhankelijkheden.
`compileOnly`	Gebruikt voor de compilatie van de huidige module en is niet beschikbaar tijdens runtime of tijdens de compilatie van andere modules.	Gebruikt voor API’s die een implementatie van derden hebben die beschikbaar is tijdens runtime.
`runtimeOnly`	Beschikbaar tijdens runtime, maar niet zichtbaar tijdens het compileren van een module.

Afhankelijkheid van de standaardbibliotheek

Een afhankelijkheid van een standaardbibliotheek (stdlib) in elke broncodeverzameling wordt automatisch toegevoegd. De versie van de standaard bibliotheek is gelijk aan de versie van de Kotlin Gradle plugin.

Voor platform-specifieke bron sets, wordt de corresponderende platform-specifieke variant van de bibliotheek gebruikt, terwijl een gemeenschappelijke standaard bibliotheek wordt toegevoegd aan de rest. De Kotlin Gradle plugin zal de juiste JVM-standaardbibliotheek selecteren, afhankelijk van de kotlinOptions.jvmTarget compileroptie van uw Gradle-buildscript.

Als u een standaardbibliotheekafhankelijkheid expliciet declareert (bijvoorbeeld als u een andere versie nodig hebt), zal de Kotlin Gradle plugin deze niet overschrijven of een tweede standaardbibliotheek toevoegen.

Als u helemaal geen standaard bibliotheek nodig hebt, kunt u de opt-out vlag toevoegen aan de gradle.properties:

kotlin.stdlib.default.dependency=false

Set dependencies on test libraries

De kotlin.test API is beschikbaar voor het testen van verschillende Kotlin projecten.

Voeg de overeenkomstige afhankelijkheden op testbibliotheken in:

Voor commonTest, voeg de kotlin-test-common en kotlin-test-annotations-common afhankelijkheden toe.
Voor JVM targets, gebruik kotlin-test-junit of kotlin-test-testng voor de overeenkomstige asserter implementatie en annotaties mapping.
Voor Kotlin/JS targets, voeg kotlin-test-js toe als een test afhankelijkheid.

Kotlin/Native targets hebben geen extra test afhankelijkheden nodig, en de kotlin.test API implementaties zijn ingebouwd.

U kunt steno gebruiken voor een afhankelijkheid van een Kotlin-module, bijvoorbeeld, kotlin(“test”) voor “org.jetbrains.kotlin:kotlin-test”.

Stel een afhankelijkheid in van een kotlinx-bibliotheek

Als u een kotlinx-bibliotheek gebruikt en een platform-specifieke afhankelijkheid nodig hebt, kunt u platform-specifieke varianten van bibliotheken gebruiken met achtervoegsels zoals -jvm of -js, bijvoorbeeld kotlinx-coroutines-core-jvm. U kunt in plaats daarvan ook de basisartefactnaam van de bibliotheek gebruiken – kotlinx-coroutines-core.

kotlin { sourceSets { jvmMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.2' } } }}

Als u een multiplatformbibliotheek gebruikt en afhankelijk moet zijn van de gedeelde code, stelt u de afhankelijkheid slechts eenmaal in de gedeelde bronset in. Gebruik de basisartefactnaam van de bibliotheek, zoals kotlinx-coroutines-core of ktor-client-core.

kotlin { sourceSets { commonMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.2' } } }}

Set dependencies at the top level

Aternatief kunt u de dependencies op het topniveau specificeren met de configuratienamen volgens het patroon <sourceSetName><DependencyType>. Dit is nuttig voor sommige ingebouwde afhankelijkheden van Gradle, zoals gradleApi(), localGroovy(), of gradleTestKit(), die niet beschikbaar zijn in de afhankelijkheids-DSL voor broncode-sets.

dependencies { commonMainImplementation 'com.example:my-library:1.0'}

dependencies { "commonMainImplementation"("com.example:my-library:1.0")}

Annotatieverwerking

Kotlin ondersteunt annonatieverwerking via de Kotlin annotatieverwerkingstool kapt.

Incrementele compilatie

De Kotlin Gradle-plugin ondersteunt incrementele compilatie. Incrementele compilatie houdt veranderingen van bronbestanden tussen builds bij, zodat alleen bestanden die door deze veranderingen worden beïnvloed, worden gecompileerd.

Incrementele compilatie wordt ondersteund voor Kotlin/JVM en Kotlin/JS projecten en is standaard ingeschakeld sinds Kotlin 1.1.1.

Er zijn verschillende manieren om de instelling uit te schakelen:

Voeg de volgende regel toe aan het gradle.properties of local.properties bestand:
- kotlin.incremental=false voor Kotlin/JVM
- kotlin.incremental.js=false voor Kotlin/JS projecten
Als opdrachtregel parameter gebruikt u -Pkotlin.incremental=false of -Pkotlin.incremental.js=false.

Merk op dat in dit geval de parameter moet worden toegevoegd aan elke volgende build, en dat elke build met uitgeschakelde incrementele compilatie de incrementele caches ongeldig maakt.

Merk op dat de eerste build in ieder geval niet incrementeel is.

Gradle build cache support

De Kotlin plugin ondersteunt Gradle build cache die de build outputs opslaat voor hergebruik in toekomstige builds.

Om de caching voor alle Kotlin taken uit te schakelen, zet u de system property flag kotlin.caching.enabled op false (voer de build uit met het argument -Dkotlin.caching.enabled=false).

Als u kapt gebruikt, merk dan op dat de kapt annotatie verwerkingstaken standaard niet in de cache worden opgeslagen. U kunt caching echter handmatig inschakelen.

Gradle configuration cache support

De configuration cache is beschikbaar in Gradle 6.5 en later als een experimentele functie. U kunt op de Gradle-releases pagina controleren of deze is gepromoveerd tot stable.

De Kotlin-plugin ondersteunt de Gradle-configuratiecache, die het bouwproces versnelt door de resultaten van de configuratiefase opnieuw te gebruiken.

Zie de Gradle-documentatie om te leren hoe u de configuratiecache inschakelt. Zodra u de configuratie cache functie inschakelt, zal de Kotlin Gradle plugin deze gaan gebruiken.

Compiler opties

Om extra compilatie opties op te geven, gebruikt u de kotlinOptions eigenschap van een Kotlin compilatie taak.

Wanneer de JVM wordt getarget, heten de taken compileKotlin voor productie code en compileTestKotlin voor test code. De taken voor aangepaste bronsets worden genoemd volgens het compile<Name>Kotlin patroon.

De namen van de taken in Android Projecten bevatten de namen van de build-varianten en volgen het patroon compile<BuildVariant>Kotlin, bijvoorbeeld compileDebugKotlin, compileReleaseUnitTestKotlin.

Bij het targeten van JavaScript, worden de taken respectievelijk compileKotlinJs en compileTestKotlinJs genoemd, en compile<Name>KotlinJs voor aangepaste bronsets.

Om een enkele taak te configureren, gebruikt u de naam. Voorbeelden:

compileKotlin { kotlinOptions.suppressWarnings = true}//orcompileKotlin { kotlinOptions { suppressWarnings = true }}

Merk op dat met Gradle Kotlin DSL, u de taak eerst uit de tasks van het project moet halen.

Gebruik de types Kotlin2JsCompile en KotlinCompileCommon voor de JS en Common targets, dienovereenkomstig.

Het is ook mogelijk om alle Kotlin compilatietaken in het project te configureren:

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { kotlinOptions { /*...*/ }}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach { kotlinOptions { /*...*/ }}

De complete lijst met opties voor de Gradle taken is de volgende:

Attributen gemeenschappelijk voor JVM, JS, en JS DCE

Naam	Beschrijving	Mogelijke waarden	Standaardwaarde
`allWarningsAsErrors`	Meld een fout als er waarschuwingen zijn	Meld een fout als er waarschuwingen		false
`suppressWarnings`	Genereer geen waarschuwingen		false
`verbose`	Inschakelen van verbose logging		false
`freeCompilerArgs`	Een lijst met extra compiler argumenten

Attributen gemeenschappelijk voor JVM en JS

Attributen specifiek voor JVM

Naam	Beschrijving	Mogelijke waarden	Standaardwaarde
`javaParameters`	Genereer metadata voor Java 1.8 reflectie op methodeparameters		false
`jdkHome`	Integreer een aangepaste JDK vanaf de opgegeven locatie in het classpath in plaats van de standaard JAVA_HOME
`jvmTarget`	Target-versie van de gegenereerde JVM-bytecode	“1.6”, “1.8”, “9”, “10”, “11”, “12”, “13”, “14”, “15”	“1.6”
`noJdk`	De Java runtime niet automatisch opnemen in het classpath		false
`noReflect`	De Kotlin-reflectie niet automatisch opnemen in het classpath		true
`noStdlib`	Doe niet automatisch de Kotlin/JVM stdlib en Kotlin reflection in het classpath		true
`useIR`	Gebruik het IR-backend		false

Attributen specifiek voor JS

Naam	Beschrijving	Mogelijke waarden	Afwijkwaarde
`friendModulesDisabled`	Export interne verklaring uitschakelen		false
`main`	Neem aan of de `main` functie bij uitvoering moet worden aangeroepen	“call”, “noCall”	“oproep”
`metaInfo`	Genereer .meta.js en .kjsm bestanden met metadata. Gebruik deze om een bibliotheek te maken		true
`moduleKind`	Het soort JS-module dat door de compiler wordt gegenereerd	“umd”, “commonjs”, “amd”, “plain”	“umd”
`noStdlib`	De standaard Kotlin/JS stdlib niet automatisch opnemen in de afhankelijkheden van de compilatie		true
`outputFile`	Destination *.js bestand voor het compilatieresultaat		“<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js”
`sourceMap`	Bronnenkaart genereren		true
`sourceMapEmbedSources`	Bronnenbestanden opnemen in bronnenkaart	“nooit”, “altijd”, “inlining”
`sourceMapPrefix`	Voeg het opgegeven voorvoegsel toe aan paden in de bronmap
`target`	Genereer JS-bestanden voor specifieke ECMA-versie	“v5”	“v5”
`typedArrays`	Translate primitive arrays to JS typed arrays		true

Generating documentation

Om documentatie voor Kotlin-projecten te genereren, Dokka gebruiken;raadpleeg de Dokka README voor configuratie-instructies. Dokka ondersteunt mixed-language projecten en kan output in meerdere formaten genereren, inclusief standaard JavaDoc.

OSGi

Voor OSGi ondersteuning zie de Kotlin OSGi pagina.

Gebruik Gradle Kotlin DSL

Wanneer u Gradle Kotlin DSL gebruikt, pas dan de Kotlin plugins toe met het plugins { ... } blok. Als u ze toepast met apply { plugin(...) } in plaats daarvan, kunt u onopgeloste verwijzingen tegenkomen naar de extensies gegenereerd door Gradle Kotlin DSL. Om dat op te lossen, kunt u commentaar uit de foutieve toepassingen, voer de Gradle taak kotlinDslAccessorsSnapshot, dan uncomment de toepassingen terug en voer de build opnieuw uit of importeer het project opnieuw in de IDE.