Användning av Gradle

Posted on by admin

Redigera sidan

För att bygga ett Kotlin-projekt med Gradle bör du tillämpa Kotlin Gradle-pluginet på ditt projekt och konfigurera beroenden.

Plugin och versioner

Använd Kotlin Gradle-plugin genom att använda Gradle plugins DSL.

Kotlin Gradle-plugin 1.4.30 fungerar med Gradle 5.4 och senare. Plugin kotlin-multiplatformkräver Gradle 6.0 eller senare.

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

Platshållaren <...> bör ersättas med ett av de namn på plugin som finns i ytterligare avsnitt.

Targeting multiple platforms

Projekt som riktar sig till flera plattformar, så kallade multiplattformsprojekt, kräver insticksmodulen kotlin-multiplatform. Läs mer om insticksmodulen.

Insticksmodulen kotlin-multiplatform fungerar med Gradle 6.0 eller senare.

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

Målinriktning på JVM

För att målinrikta JVM:n tillämpar du insticksmodulen Kotlin JVM.

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

version ska vara bokstavlig i det här blocket och kan inte tillämpas från ett annat byggskript.

Alternativt kan du använda det äldre apply plugin tillvägagångssättet: 

apply plugin: 'kotlin'

Det rekommenderas inte att du tillämpar Kotlin-plugins med apply i Gradle Kotlin DSL – se varför.

Kotlin- och Javakällor

Kotlin-källor kan lagras tillsammans med Javakällor i samma mapp, eller placeras till olika mappar. Standardkonventionen är att använda olika mappar:

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

Korresponderande sourceSetsegenskap bör uppdateras om man inte använder standardkonventionen:

sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' main.java.srcDirs += 'src/main/myJava'}
sourceSets.main { java.srcDirs("src/main/myJava", "src/main/myKotlin")}

Målinriktning på JavaScript

När du riktar in dig enbart på JavaScript använder du insticksprogrammet kotlin-js. Läs mer

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

Kotlin- och Javakällor

Detta insticksmodul fungerar endast för Kotlin-filer, så det rekommenderas att du förvarar Kotlin- och Javafiler separat (om projektet innehåller Javafiler). Om du inte lagrar dem separat , ange källmappen i blocket sourceSets:

kotlin { sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' }}
kotlin { sourceSets.apply { kotlin.srcDir("src/main/myKotlin") }}

Targeting Android

Det rekommenderas att du använder Android Studio för att skapa Android-program. Lär dig hur du använder Android Gradle-plugin.

Konfigurera beroenden

För att lägga till ett beroende av ett bibliotek ställer du in beroendet av den erforderliga typen (till exempel implementation) i dependencies-blocket i källkodssättningen 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") } } }}

Alternativt kan du ställa in beroenden på toppnivå.

Dependetyper

Välj beroende typ baserat på dina krav.

Typ Beskrivning När du ska använda
api Används både under kompilering och vid körning och exporteras till bibliotekskonsumenter. Om någon typ från ett beroende används i den aktuella modulens offentliga API, använd ett api-beroende.
implementation Används under kompilering och vid körning för den aktuella modulen, men exponeras inte för kompilering av andra moduler som är beroende av den som har beroendet `implementation`.

Används för beroenden som behövs för en moduls interna logik.

Om en modul är en slutpunktsapplikation som inte publiceras, använd implementation beroenden istället för api beroenden.
compileOnly Används för kompilering av den aktuella modulen och är inte tillgänglig vid körning eller vid kompilering av andra moduler. Används för API:er som har en implementering från tredje part tillgänglig vid körning.
runtimeOnly Tillgänglig vid körning men syns inte under kompilering av någon modul.

Beroende på standardbiblioteket

Ett beroende på ett standardbibliotek (stdlib) i varje källkodssats läggs till automatiskt. Versionen av standardbiblioteket är densamma som versionen av Kotlin Gradle-pluginet.

För plattformsspecifika källuppsättningar används motsvarande plattformsspecifika variant av biblioteket, medan ett gemensamt standardbibliotek läggs till för resten. Kotlin Gradle-pluginet väljer lämpligt JVM-standardbibliotek beroende på kotlinOptions.jvmTarget kompileralternativet i ditt Gradle-byggnadsskript.

Om du deklarerar ett standardbiblioteksberoende explicit (till exempel om du behöver en annan version) kommer Kotlin Gradle-pluginet inte att åsidosätta det eller lägga till ett andra standardbibliotek.

Om du inte behöver ett standardbibliotek alls kan du lägga till opt-out-flaggan i gradle.properties:

kotlin.stdlib.default.dependency=false

Sätt beroenden på testbibliotek

Det kotlin.test API:et finns tillgängligt för att testa olika Kotlin-projekt.

Lägg till motsvarande beroenden på testbibliotek:

  • För commonTest lägger du till beroendena kotlin-test-common och kotlin-test-annotations-common.
  • För JVM-mål, använd kotlin-test-junit eller kotlin-test-testng för motsvarande asserter-implementation och annotationsmappning.
  • För Kotlin/JS-mål, lägg till kotlin-test-js som ett testberoende.

Kotlin/Native-mål kräver inga ytterligare testberoenden och kotlin.test API-implementationerna är inbyggda.

Du kan använda förkortning för ett beroende av en Kotlin-modul, till exempel kotlin(”test”) för ”org.jetbrains.kotlin:kotlin-test”.

Sätt ett beroende på ett kotlinx-bibliotek

Om du använder ett kotlinx-bibliotek och behöver ett plattformsspecifikt beroende kan du använda plattformsspecifika varianter av bibliotek med suffix som -jvm eller -js, till exempel kotlinx-coroutines-core-jvm. Du kan också använda bibliotekets basartefaktnamn i stället – kotlinx-coroutines-core.

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

Om du använder ett multiplattformsbibliotek och behöver vara beroende av den delade koden, ska du ange beroendet endast en gång i den delade källkoden. Använd biblioteksbasens artefaktnamn, till exempel kotlinx-coroutines-core eller ktor-client-core.

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

Sätt beroenden på den översta nivån

Alternativt kan du ange beroenden på den översta nivån med konfigurationsnamnen som följer mönstret <sourceSetName><DependencyType>. Detta är användbart för vissa Gradle-inbyggda beroenden, som gradleApi(), localGroovy() eller gradleTestKit(), som inte är tillgängliga i källuppsättningarnas beroende-DSL.

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

Anteckningsbearbetning

Kotlin har stöd för annonationsbearbetning via Kotlin-annotationsbearbetningsverktyget kapt.

Inkrementell kompilering

Pluginet för Kotlin Gradle har stöd för inkrementell kompilering. Inkrementell kompilering spårar ändringar av källkodsfiler mellan byggningar så att endast filer som påverkas av dessa ändringar kompileras.

Inkrementell kompilering stöds för Kotlin/JVM- och Kotlin/JS-projekt och är aktiverad som standard sedan Kotlin 1.1.1.1.

Det finns flera sätt att inaktivera inställningen:

  • Lägg till följande rad i gradle.properties eller local.properties-filen:
    • kotlin.incremental=false för Kotlin/JVM
    • kotlin.incremental.js=false för Kotlin/JS-projekt

  • Som kommandoradsparameter använder du -Pkotlin.incremental=false eller -Pkotlin.incremental.js=false.

    Bemärk att parametern i det här fallet ska läggas till vid varje efterföljande byggning, och varje byggning med inaktiverad inkrementell kompilering ogiltigförklarar inkrementella cacher.

Bemärk att den första byggningen inte är inkrementell i vilket fall som helst.

Stöd för Gradle build cache

Insticksmodulen för Kotlin har stöd för Gradle build cache som lagrar byggutgångarna för återanvändning i framtida byggen.

För att inaktivera cachelagringen för alla Kotlin-uppgifter ställer du in systemegenskapsflaggan kotlin.caching.enabled till false (kör byggningen med argumentet -Dkotlin.caching.enabled=false).

Om du använder kapt ska du notera att bearbetningsuppgifter för kapt-annotationer inte cachelagras som standard. Du kan dock aktivera caching för dem manuellt.

Stöd för Gradle-konfigurationscache

Konfigurationscachen finns tillgänglig i Gradle 6.5 och senare som en experimentell funktion.Du kan kontrollera sidan för Gradle-versioner för att se om den har blivit befordrad till stable.

Kotlin-pluginet har stöd för Gradle configuration cache,vilket snabbar upp byggprocessen genom att återanvända resultaten från konfigurationsfasen.

Se Gradle-dokumentationen för att lära dig hur du aktiverar configuration cache. När du har aktiverat konfigurationscache-funktionen kommer Kotlin Gradle-pluginet att börja använda den.

Kompileralternativ

För att ange ytterligare kompileringsalternativ använder du kotlinOptions-egenskapen för en Kotlin-kompileringsuppgift.

När de är inriktade på JVM kallas uppgifterna compileKotlin för produktionskod och compileTestKotlin för testkod. Uppgifterna för anpassade källkoder kallas i enlighet med mönstret compile<Name>Kotlin.

Namnen på uppgifterna i Android Projects innehåller namnen på byggvarianterna och följer mönstret compile<BuildVariant>Kotlin, t.ex. compileDebugKotlin, compileReleaseUnitTestKotlin.

När uppgifterna är inriktade på JavaScript kallas de compileKotlinJs respektive compileTestKotlinJs och compile<Name>KotlinJs för anpassade källkoder.

Om du vill konfigurera en enskild uppgift använder du dess namn. Exempel:

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

Notera att med Gradle Kotlin DSL ska du hämta uppgiften från projektets tasks först.

Använd typerna Kotlin2JsCompile och KotlinCompileCommon för JS-mål och Common-mål, i enlighet med detta.

Det är också möjligt att konfigurera alla Kotlin-kompileringsuppgifter i projektet:

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

Den fullständiga listan över alternativ för Gradle-uppgifter är följande:

Attributen är gemensamma för JVM, JS, och JS DCE

Namn Beskrivning Möjliga värden Standardvärde
allWarningsAsErrors Rapportera ett fel om det finns några varningar falskt
suppressWarnings Generera inga varningar falskt
verbose Aktivera utförlig loggningsutgång Falskt
freeCompilerArgs En lista över ytterligare kompilerargument

Attribut som är gemensamma för JVM och JS

Attribut. specifika för JVM

Namn Beskrivning Möjliga värden Standardvärde
javaParameters Generera metadata för Java 1.8 reflection on method parameters false
jdkHome Inkludera en anpassad JDK från den angivna platsen i den classpath istället för standardvärdet JAVA_HOME
jvmTarget Målversionen av den genererade JVM-bytekoden ”1.6”, ”1.8”, ”9”, ”10”, ”11”, ”12”, ”13”, ”14”, ”15” ”1.6”
noJdk Inkludera inte automatiskt Java runtime i classpath false
noReflect Inkludera inte automatiskt Kotlin reflection i classpath. classpath true
noStdlib Inkludera inte automatiskt Kotlin/JVM stdlib och Kotlin reflection i classpath true
useIR Använd IR-backend false

Attribut som är specifika för JS

Namn Beskrivning Möjliga värden Standardvärde
friendModulesDisabled Debitera export av intern deklaration falskt
main Definierar om mainfunktionen ska anropas vid exekvering ”call”, ”noCall” ”call”
metaInfo Generera .meta.js och .kjsm-filer med metadata. Används för att skapa ett bibliotek true
moduleKind Typen av JS-modul som genereras av kompilatorn ”umd”, ”commonjs”, ”amd”, ”plain” ”umd”
noStdlib Inkludera inte automatiskt standardstdlib för Kotlin/JS i kompileringsberoenden true
outputFile Destination *.js-fil för kompileringsresultatet ”<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js”
sourceMap Generera källkodsmapp true
sourceMapEmbedSources Bädda in källkodsfiler i källkodsmapp ”never”, ”always”, ”inlining”
sourceMapPrefix Lägg till det angivna prefixet till sökvägar i källkodsmappningen
target Generera JS-filer för en specifik ECMA-version ”v5” ”v5”
typedArrays Översätt primitiva matriser till JS-typade matriser true

Genererar dokumentation

För att generera dokumentation för Kotlin-projekt, använda Dokka;Se Dokka README för konfigurationsinstruktioner. Dokka stöder projekt med blandade språk och kan generera utdata i flera format, inklusive standard JavaDoc.

OSGi

För OSGi-stöd se sidan Kotlin OSGi.

Användning av Gradle Kotlin DSL

När du använder Gradle Kotlin DSL tillämpar du Kotlin-plugins med hjälp av blocket plugins { ... }. Om du tillämpar dem med apply { plugin(...) } istället kan du stöta på olösta referenser till de tillägg som genereras av Gradle Kotlin DSL. För att lösa det kan du kommentera ut de felaktiga användningarna, köra Gradle-uppgiften kotlinDslAccessorsSnapshot, sedan avkommentera användningarna igen och köra byggandet på nytt eller återimportera projektet i IDE.

Related Posts

Ditt blodtryck är 102 över 50?

Blodtryck 102/50 – vad betyder det?Blodtryck 102/50 på blodtrycksdiagrammetKontrollera ett annat värde?Blodtryck 102/50 på blodtrycksskalanVad du bör veta om ett…

Lämna ett svar

Din e-postadress kommer inte publiceras.