Brug af Gradle

Rediger side

For at bygge et Kotlin-projekt med Gradle skal du anvende Kotlin Gradle-pluginprogrammet til dit projekt og konfigurere afhængigheder.

Plugin og versioner

Anvend Kotlin Gradle-plugin ved hjælp af Gradle plugins DSL.

Kotlin Gradle-plugin 1.4.30 fungerer med Gradle 5.4 og nyere versioner. kotlin-multiplatform plugin’et kræver Gradle 6.0 eller nyere.

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

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

Placetholderen <...> skal erstattes med et af de plugin-navne, der kan findes i yderligere afsnit.

Targeting multiple platforms

Projekter, der er rettet mod flere platforme, kaldet multiplatformsprojekter, kræver plugin kotlin-multiplatform. Få mere at vide om plugin’et.

kotlin-multiplatformplugin’et fungerer med Gradle 6.0 eller nyere.

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

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

Targeting af JVM

For at målrette JVM’en skal du anvende Kotlin JVM-plugin’et.

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

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

Den version skal være bogstavelig i denne blok, og den kan ikke anvendes fra et andet build-script.

Alternativt kan du bruge den ældre apply plugin-tilgang:

apply plugin: 'kotlin'

Det anbefales ikke, at du anvender Kotlin-plugins med apply i Gradle Kotlin DSL – se hvorfor.

Kotlin- og Java-kilder

Kotlin-kilder kan gemmes sammen med Java-kilder i samme mappe eller placeres i forskellige mapper. Standardkonventionen er at bruge forskellige mapper:

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

Den tilsvarende sourceSets-egenskab skal opdateres, hvis du ikke bruger standardkonventionen:

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

Ved målretning af kun JavaScript skal du bruge kotlin-js-pluginet. Læs mere

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

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

Kotlin- og Java-kilder

Dette plugin fungerer kun for Kotlin-filer, så det anbefales, at du opbevarer Kotlin- og Java-filer separat (hvis projektet indeholder Java-filer). Hvis du ikke gemmer dem separat , skal du angive kildemappen i blokken sourceSets:

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

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

Targeting Android

Det anbefales, at du bruger Android Studio til at oprette Android-applikationer. Lær, hvordan du bruger Android Gradle-plugin.

Konfigurering af afhængigheder

For at tilføje en afhængighed af et bibliotek skal du angive afhængigheden af den krævede type (f.eks. implementation) i dependencies-blokken i DSL-sættene for kildesæt.

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") } } }}

Alternativt kan du indstille afhængigheder på topniveau.

Afhængighedstyper

Vælg afhængighedstypen ud fra dine krav.

Afhængighed af standardbiblioteket

En afhængighed af et standardbibliotek (stdlib) i hvert kildesæt tilføjes automatisk. Versionen af standardbiblioteket er den samme som versionen af Kotlin Gradle-plugin’et.

For platformsspecifikke kildesæt bruges den tilsvarende platformsspecifikke variant af biblioteket, mens et fælles standardbibliotek tilføjes til resten. Kotlin Gradle-pluginprogrammet vælger det passende JVM-standardbibliotek afhængigt af kotlinOptions.jvmTarget compilerindstillingen i dit Gradle-byggescript.

Hvis du erklærer en standardbiblioteksafhængighed eksplicit (f.eks. hvis du har brug for en anden version), vil Kotlin Gradle-pluginprogrammet ikke tilsidesætte den eller tilføje et andet standardbibliotek.

Hvis du slet ikke har brug for et standardbibliotek, kan du tilføje opt-out-flaget til gradle.properties:

kotlin.stdlib.default.dependency=false

Sæt afhængigheder på testbiblioteker

Det kotlin.test API er tilgængeligt for test af forskellige Kotlin-projekter.

Føj de tilsvarende afhængigheder på testbiblioteker til:

• For commonTest skal du tilføje kotlin-test-common og kotlin-test-annotations-common-afhængighederne.
• For JVM-mål skal du bruge kotlin-test-junit eller kotlin-test-testng til den tilsvarende asserter-implementering og annotationstilknytning.
• For Kotlin/JS-mål skal du tilføje kotlin-test-js som en testafhængighed.

Kotlin/Native-mål kræver ikke yderligere testafhængigheder, og kotlin.test API-implementeringerne er indbygget.

Du kan bruge en forkortelse for en afhængighed af et Kotlin-modul, f.eks. kotlin(“test”) for “org.jetbrains.kotlin:kotlin-test”.

Sæt en afhængighed af et kotlinx-bibliotek

Hvis du bruger et kotlinx-bibliotek og har brug for en platformsspecifik afhængighed, kan du bruge platformsspecifikke varianter af biblioteker med suffikser som -jvm eller -js, f.eks. kotlinx-coroutines-core-jvm. Du kan også bruge bibliotekets basisartefaktnavn i stedet – kotlinx-coroutines-core.

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

Hvis du bruger et bibliotek til flere platforme og har brug for at være afhængig af den delte kode, skal du kun angive afhængigheden én gang i det delte kildesæt. Brug bibliotekets basisartefaktnavn, f.eks. kotlinx-coroutines-core eller ktor-client-core.

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

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

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

Annotationsbehandling

Kotlin understøtter annotationsbehandling via Kotlin-annotationsbehandlingsværktøjet kapt.

Inkrementel kompilering

Kotlin Gradle-plugin’et understøtter inkrementel kompilering. Inkrementel kompilering sporer ændringer af kildefilerne mellem builds, så kun filer, der er berørt af disse ændringer, vil blive kompileret.

Inkrementel kompilering understøttes for Kotlin/JVM- og Kotlin/JS-projekter og er aktiveret som standard siden Kotlin 1.1.1.1.

Der er flere måder at deaktivere indstillingen på:

• Føj følgende linje til gradle.properties eller local.properties-filen:
  • kotlin.incremental=false for Kotlin/JVM
  • kotlin.incremental.js=false for Kotlin/JS-projekter

• Som kommandolinjeparameter skal du bruge -Pkotlin.incremental=false eller -Pkotlin.incremental.js=false.

  Bemærk, at parameteren i dette tilfælde skal tilføjes til hvert efterfølgende build, og ethvert build med deaktiveret inkrementel kompilering ugyldiggør inkrementelle caches.

Bemærk, at det første build ikke er inkrementelt under alle omstændigheder.

Understøttelse af Gradle build cache

Kotlin-plugin’et understøtter Gradle build cache, der gemmer build-output til genbrug i fremtidige builds.

For at deaktivere caching for alle Kotlin-opgaver skal du indstille systemegenskabsflaget kotlin.caching.enabled til false (kør buildet med argumentet -Dkotlin.caching.enabled=false).

Hvis du bruger kapt, skal du være opmærksom på, at kapt-annotationsbehandlingsopgaverne ikke caches som standard. Du kan dog aktivere caching for dem manuelt.

Understøttelse af Gradle-konfigurationscache

Konfigurationscachen er tilgængelig i Gradle 6.5 og nyere som en eksperimentel funktion. du kan se på siden for Gradle-udgivelser, om den er blevet forfremmet til stable.

Kotlin-plugin’et understøtter Gradle-konfigurationscache,som fremskynder byggeprocessen ved at genbruge resultaterne fra konfigurationsfasen.

Se Gradle-dokumentationenfor at lære, hvordan du aktiverer konfigurationscachen. Når du aktiverer konfigurationscachefunktionen, vil Kotlin Gradle-pluginprogrammet begynde at bruge den.

Compilerindstillinger

For at angive yderligere kompileringsindstillinger skal du bruge kotlinOptions-egenskaben for en Kotlin-kompileringsopgave.

Når opgaverne er rettet mod JVM’en, kaldes de compileKotlin for produktionskode og compileTestKotlin for testkode. Opgaverne for brugerdefinerede kildesæt kaldes i overensstemmelse med mønsteret compile<Name>Kotlin.

Navnene på opgaverne i Android Projects indeholder navnene på byggevarianterne og følger mønsteret compile<BuildVariant>Kotlin, f.eks. compileDebugKotlin, compileReleaseUnitTestKotlin.

Når de er rettet mod JavaScript, kaldes opgaverne henholdsvis compileKotlinJs og compileTestKotlinJs og compile<Name>KotlinJs for brugerdefinerede kildesæt.

For at konfigurere en enkelt opgave skal du bruge navnet på den. Eksempler:

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

Bemærk, at med Gradle Kotlin DSL skal du hente opgaven fra projektets tasks først.

Brug typerne Kotlin2JsCompile og KotlinCompileCommon for JS-målene og Common-målene, i overensstemmelse hermed.

Det er også muligt at konfigurere alle Kotlin-kompileringsopgaver i projektet:

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

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