Utilizarea Gradle

Edit Page

Pentru a construi un proiect Kotlin cu Gradle, trebuie să aplicați plugin-ul Kotlin Gradle la proiectul dumneavoastră și să configurați dependențele.

Plugin și versiuni

Aplicați pluginul Kotlin Gradle folosind Gradle plugins DSL.

Plinul Kotlin Gradle 1.4.30 funcționează cu Gradle 5.4 și versiunile ulterioare. Plugin-ul kotlin-multiplatformnecesită Gradle 6.0 sau o versiune ulterioară.

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

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

Substitutul <...>trebuie înlocuit cu unul dintre numele plugin-urilor care pot fi găsite în secțiunile ulterioare.

Tintirea mai multor platforme

Proiectele care vizează mai multe platforme, numite proiecte multiplatformă, necesită plugin-ul kotlin-multiplatform. Aflați mai multe despre acest plugin.

Principiul kotlin-multiplatform funcționează cu Gradle 6.0 sau o versiune ulterioară.

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

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

Tintirea JVM

Pentru a ținti JVM, aplicați pluginul Kotlin JVM.

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

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

Literalul version trebuie să fie literal în acest bloc și nu poate fi aplicat dintr-un alt script de compilare.

Alternativ, puteți utiliza abordarea mai veche apply plugin:

apply plugin: 'kotlin'

Nu este recomandat să aplicați plugin-uri Kotlin cu apply în Gradle Kotlin DSL – vedeți de ce.

Surse Kotlin și Java

Sursele Kotlin pot fi stocate împreună cu sursele Java în același dosar, sau plasate în dosare diferite. Convenția implicită este folosirea unor dosare diferite:

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

Proprietatea sourceSets corespunzătoare trebuie actualizată dacă nu se folosește convenția implicită:

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

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

Tintirea JavaScript

Când se țintește doar JavaScript, folosiți pluginul kotlin-js. Aflați mai multe

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

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

Surse Kotlin și Java

Acest plugin funcționează numai pentru fișierele Kotlin, astfel încât este recomandat să păstrați separat fișierele Kotlin și Java (în cazul în care proiectul conține fișiere Java). Dacă nu le păstrați separat , specificați folderul sursei în blocul sourceSets:

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

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

Tarifarea Android

Se recomandă să utilizați Android Studio pentru crearea de aplicații Android. Aflați cum să utilizați pluginul Android Gradle.

Configurarea dependențelor

Pentru a adăuga o dependență de o bibliotecă, setați dependența de tipul necesar (de exemplu, implementation) în blocul dependencies din DSL-ul de setări sursă.

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, puteți seta dependențele la nivel superior.

Tipuri de dependență

Alegeți tipul de dependență în funcție de cerințele dumneavoastră.

Dependență de biblioteca standard

Se adaugă automat o dependență de o bibliotecă standard (stdlib) în fiecare set de surse. Versiunea bibliotecii standard este aceeași cu versiunea pluginului Kotlin Gradle.

Pentru seturile de surse specifice platformei, se utilizează varianta specifică platformei corespunzătoare a bibliotecii, în timp ce pentru restul se adaugă o bibliotecă standard comună. Plugin-ul Kotlin Gradle va selecta biblioteca standard JVM corespunzătoare în funcție de opțiunea de compilare kotlinOptions.jvmTarget din scriptul de compilare Gradle.

Dacă declarați explicit o dependență de bibliotecă standard (de exemplu, dacă aveți nevoie de o versiune diferită), plugin-ul Kotlin Gradle nu o va suprascrie și nu va adăuga o a doua bibliotecă standard.

Dacă nu aveți nevoie deloc de o bibliotecă standard, puteți adăuga stegulețul opt-out la gradle.properties:

kotlin.stdlib.default.dependency=false

Set dependencies on test libraries

API-ul kotlin.test este disponibil pentru testarea diferitelor proiecte Kotlin.

Adaugați dependențele corespunzătoare pe bibliotecile de testare:

• Pentru commonTest, adăugați dependențele kotlin-test-common și kotlin-test-annotations-common.
• Pentru țintele JVM, utilizați kotlin-test-junit sau kotlin-test-testng pentru implementarea asertorului corespunzător și maparea adnotărilor.
• Pentru țintele Kotlin/JS, adăugați kotlin-test-js ca dependență de testare.

Țintele Kotlin/Native nu necesită dependențe de testare suplimentare, iar implementările API kotlin.test sunt încorporate.

Puteți utiliza prescurtări pentru o dependență de un modul Kotlin, de exemplu, kotlin(„test”) pentru „org.jetbrains.kotlin:kotlin-test”.

Stabilește o dependență de o bibliotecă kotlinx

Dacă utilizați o bibliotecă kotlinx și aveți nevoie de o dependență specifică platformei, puteți utiliza variante de biblioteci specifice platformei cu sufixe precum -jvm sau -js, de exemplu, kotlinx-coroutines-core-jvm. De asemenea, puteți utiliza în schimb numele artefactului de bază al bibliotecii – kotlinx-coroutines-core.

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

Dacă utilizați o bibliotecă multiplatformă și aveți nevoie să depindeți de codul partajat, setați dependența o singură dată în setul de surse partajate. Folosiți numele artefactului de bază al bibliotecii, cum ar fi kotlinx-coroutines-core sau ktor-client-core.

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

Setați dependențele la nivel superior

Alternativ, puteți specifica dependențele la nivel superior cu nume de configurare care urmează modelul <sourceSetName><DependencyType>. Acest lucru este util pentru unele dependențe încorporate Gradle, cum ar fi gradleApi(), localGroovy() sau gradleTestKit(), care nu sunt disponibile în DSL-ul de dependență a seturilor de surse.

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

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

Procesarea adnotărilor

Kotlin suportă procesarea adnotărilor prin intermediul instrumentului de procesare a adnotărilor Kotlin kapt.

Compilare incrementală

Plinul Kotlin Gradle suportă compilarea incrementală. Compilarea incrementală urmărește modificările fișierelor sursă între compilări, astfel încât doar fișierele afectate de aceste modificări să fie compilate.

Compilarea incrementală este suportată pentru proiectele Kotlin/JVM și Kotlin/JS și este activată în mod implicit de la Kotlin 1.1.1.1.

Există mai multe moduri de a dezactiva setarea:

• Adaugați următoarea linie la fișierul gradle.properties sau local.properties:
  • kotlin.incremental=false pentru proiecte Kotlin/JVM
  • kotlin.incremental.js=false pentru proiecte Kotlin/JS

• Ca parametru de linie de comandă, utilizați -Pkotlin.incremental=false sau -Pkotlin.incremental.js=false.

  Rețineți că, în acest caz, parametrul trebuie adăugat la fiecare compilare ulterioară, iar orice compilare cu compilarea incrementală dezactivată invalidează cache-urile incrementale.

Rețineți că prima compilare nu este incrementală în nici un caz.

Suportul cache-ului de compilare Gradle

Principalul Kotlin suportă cache-ul de compilare Gradle care stochează ieșirile de compilare pentru reutilizare în compilări viitoare.

Pentru a dezactiva cache-ul pentru toate sarcinile Kotlin, setați flag-ul proprietății de sistem kotlin.caching.enabled la false (rulați compilarea cu argumentul -Dkotlin.caching.enabled=false).

Dacă utilizați kapt, rețineți că sarcinile de procesare a adnotărilor kapt nu sunt stocate în cache în mod implicit. Cu toate acestea, puteți activa caching-ul pentru ele manual.

Suportul cache-ului de configurare Gradle

Cache-ul de configurare este disponibil în Gradle 6.5 și versiunile ulterioare ca o caracteristică experimentală. puteți verifica pagina de versiuni Gradle pentru a vedea dacă a fost promovat la stabil.

Principiul Kotlin suportă cache-ul de configurare Gradle,care accelerează procesul de construire prin reutilizarea rezultatelor fazei de configurare.

Vezi documentația Gradlepentru a afla cum să activezi cache-ul de configurare. Odată ce ați activat caracteristica cache de configurare, pluginul Gradle Kotlin va începe să o folosească.

Opțiuni de compilare

Pentru a specifica opțiuni suplimentare de compilare, utilizați proprietatea kotlinOptions a unei sarcini de compilare Kotlin.

Când vizează JVM, sarcinile se numesc compileKotlin pentru codul de producție și compileTestKotlinpentru codul de testare. Sarcinile pentru seturile de surse personalizate se numesc în conformitate cu modelul compile<Name>Kotlin.

Numele sarcinilor din Android Projects conțin numele variantei de compilare și urmează modelul compile<BuildVariant>Kotlin, de exemplu, compileDebugKotlin, compileReleaseUnitTestKotlin.

Când vizează JavaScript, sarcinile se numesc compileKotlinJs și, respectiv, compileTestKotlinJs și compile<Name>KotlinJs pentru seturile de surse personalizate.

Pentru a configura o singură sarcină, utilizați numele acesteia. Exemple:

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

Rețineți că, cu Gradle Kotlin DSL, trebuie să obțineți mai întâi sarcina din tasks din proiect.

Utilizați tipurile Kotlin2JsCompile și KotlinCompileCommon pentru țintele JS și Common, în mod corespunzător.

De asemenea, este posibil să configurați toate sarcinile de compilare Kotlin din proiect:

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

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

Lista completă de opțiuni pentru sarcinile Gradle este următoarea:

Atribute comune pentru JVM, JS, și JS DCE

Atributuri comune pentru JVM și JS

Atributuri specifice pentru JVM

.

Atribute specifice pentru JS

.

.

Generarea de documentație

Pentru a genera documentație pentru proiectele Kotlin, utilizați Dokka;vă rugăm să consultați Dokka READMEpentru instrucțiuni de configurare. Dokka acceptă proiecte cu limbaj mixt și poate genera ieșiri în mai multe formate, inclusiv JavaDoc standard.

OSGi

Pentru suportul OSGi, consultați pagina Kotlin OSGi.

Utilizarea Gradle Kotlin DSL

Când folosiți Gradle Kotlin DSL, aplicați plugin-urile Kotlin folosind blocul plugins { ... }. Dacă le aplicați în schimb cu apply { plugin(...) }, este posibil să întâlniți referințe nerezolvate la extensiile generate de Gradle Kotlin DSL. Pentru a rezolva acest lucru, puteți să comentați utilizările eronate, să rulați sarcina Gradle kotlinDslAccessorsSnapshot, apoi să decomentați utilizările înapoi și să rulați din nou compilarea sau să reimportați proiectul în IDE.

.