Käyttämällä Gradlea

Muokkaa sivua

Voidaksesi rakentaa Kotlin-projektin Gradlella, sinun on sovellettava Kotlin Gradle -laajennusta projektiisi ja määritettävä riippuvuudet.

Lisäosa ja versiot

Sovita Kotlin Gradle -lisäosa käyttämällä Gradlen lisäosien DSL:ää.

Kotlin Gradle -lisäosa 1.4.30 toimii Gradle 5.4:n ja uudempien kanssa. kotlin-multiplatformLisäosa vaatii Gradle 6.0:n tai uudemman.

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

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

Sijoitusmerkki <...> tulee korvata jollakin lisäosan nimistä, jotka löytyvät myöhemmistä kappaleista.

Targeting multiple platforms

Monelle alustalle kohdistuvat projektit, joita kutsutaan multiplatform-projekteiksi, vaativat kotlin-multiplatform-lisäosan. Lue lisää lisäosasta.

kotlin-multiplatform-lisäosa toimii Gradle 6.0:n tai uudemman kanssa.

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

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

JavM:n kohdistaminen

JavM:n kohdistaminen edellyttää Kotlin JVM-lisäosan käyttöä.

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

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

Tässä lohkossa version tulee olla kirjaimellinen, eikä sitä voi soveltaa toisesta build-skriptistä.

Vaihtoehtoisesti voit käyttää vanhempaa apply plugin lähestymistapaa:

apply plugin: 'kotlin'

Ei ole suositeltavaa soveltaa Kotlin-liitännäisiä apply:llä Gradlen Kotlin DSL:ssä – katso miksi.

Kotlin- ja Java-lähteet

Kotlin-lähteet voidaan säilyttää Java-lähteiden kanssa samassa kansiossa tai sijoittaa eri kansioihin. Oletuskäytäntö on eri kansioiden käyttäminen:

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

Vastaava sourceSets-ominaisuus tulisi päivittää, jos ei käytetä oletuskäytäntöä:

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

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

Javaskriptin kohdistaminen

Koska kohdistetaan vain JavaScriptiä, käytetään kotlin-js-lisäosaa. Lisätietoja

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

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

Kotlin- ja Java-lähteet

Tämä lisäosa toimii vain Kotlin-tiedostoille, joten Kotlin- ja Java-tiedostot kannattaa pitää erillään toisistaan (jos projekti sisältää Java-tiedostoja). Jos et säilytä niitä erikseen , määritä lähdekansio lohkossa sourceSets:

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

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

Targeting Android

Suositellaan, että käytät Android Studiota Android-sovellusten luomiseen. Opi käyttämään Android Gradle -lisäosaa.

Riippuvuuksien määrittäminen

Lisätäksesi riippuvuuden kirjastosta, aseta vaaditun tyyppinen riippuvuus (esimerkiksi implementation) lähdekoodiasetusten DSL:n dependencies-lohkossa.

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

Vaihtoehtoisesti voit asettaa riippuvuudet ylätasolla.

Riippuvuustyypit

Valitse riippuvuustyyppi tarpeidesi mukaan.

Vakiokirjastoriippuvuus

Kussakin lähdekoodisarjassa lisätään automaattisesti riippuvuus standardikirjastosta (stdlib). Standardikirjaston versio on sama kuin Kotlin Gradle-lisäosan versio.

Alustakohtaisissa lähdekoodisarjoissa käytetään kirjaston vastaavaa alustakohtaista muunnosta, kun taas muihin lisätään yhteinen standardikirjasto. Kotlin Gradle -liitännäinen valitsee sopivan JVM-standardikirjaston Gradle-rakennusskriptin kotlinOptions.jvmTarget-kääntäjävaihtoehdon mukaan.

Jos ilmoitat standardikirjastoriippuvuuden eksplisiittisesti (esimerkiksi jos tarvitset eri versiota), Kotlin Gradle -liitännäinen ei ohita sitä tai lisää toista standardikirjastoa.

Jos et tarvitse vakiokirjastoa lainkaan, voit lisätä opt-out-lipukkeen gradle.properties:

kotlin.stdlib.default.dependency=false

Testikirjastojen riippuvuuksien asettaminen

Testauskirjastojen kotlin.test API on käytettävissä eri Kotlin-projektien testaamiseen.

Lisää vastaavat riippuvuudet testikirjastoihin:

• Lisää commonTest:lle kotlin-test-common ja kotlin-test-annotations-common riippuvuudet.
• JVM-kohteissa käytä kotlin-test-junit tai kotlin-test-testng vastaavaa asserter-toteutusta ja annotaatiokartoitusta.
• Kotlin/JS-kohteissa lisää kotlin-test-js testiriippuvuudeksi.

Kotlin/Native-kohteet eivät vaadi ylimääräisiä testiriippuvuuksia ja kotlin.test API-toteutukset ovat sisäänrakennettuja.

Voit käyttää lyhennettä Kotlin-moduulin riippuvuudesta, esimerkiksi kotlin(”test”) for ”org.jetbrains.kotlin:kotlin-test”.

Asioita riippuvuus kotlinx-kirjastosta

Jos käytät kotlinx-kirjastoa ja tarvitset alustakohtaisen riippuvuuden, voit käyttää kirjastojen alustakohtaisia muunnoksia, joissa on päätteet kuten -jvm tai -js, esimerkiksi kotlinx-coroutines-core-jvm. Voit myös käyttää sen sijaan kirjaston perusartefaktin nimeä – kotlinx-coroutines-core.

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

Jos käytät monialustakirjastoa ja tarvitset riippuvuutta jaetusta koodista, aseta riippuvuus vain kerran jaetussa lähdekoodissa. Käytä kirjaston perusartefaktin nimeä, kuten kotlinx-coroutines-core tai ktor-client-core.

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

Ariippuvuuksien asettaminen ylimmällä tasolla

Vaihtoehtoisesti voit määritellä riippuvuudet ylimmällä tasolla siten, että kokoonpanonimet noudattavat mallia <sourceSetName><DependencyType>. Tämä on hyödyllistä joidenkin Gradlen sisäänrakennettujen riippuvuuksien, kuten gradleApi(), localGroovy() tai gradleTestKit(), kohdalla, jotka eivät ole käytettävissä lähdekoodijoukkojen riippuvuus-DSL:ssä.

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

Annotaatioiden käsittely

Kotlin tukee annotaatioiden käsittelyä Kotlin-annotaatioiden käsittelytyökalun kapt kautta.

Inkrementaalinen kääntäminen

Kotlin Gradle-lisäosa tukee inkrementaalista kääntämistä. Inkrementaalinen kääntäminen seuraa lähdetiedostojen muutoksia buildien välillä, joten vain ne tiedostot, joihin nämä muutokset vaikuttavat, käännettäisiin.

Inkrementaalinen kääntäminen on tuettu Kotlin/JVM- ja Kotlin/JS-projekteille, ja se on oletusarvoisesti otettu käyttöön Kotlin 1.1.1:stä lähtien.

Esimerkkejä asetuksen poistamiseksi käytöstä on useita:

• Lisää seuraava rivi gradle.properties– tai local.properties-tiedostoon:
  • kotlin.incremental=false Kotlin/JVM
  • kotlin.incremental.js=false Kotlin/JS-projekteille

• Komentoriviparametrina käytä -Pkotlin.incremental=false tai -Pkotlin.incremental.js=false.

  Huomaa, että tässä tapauksessa parametri on lisättävä jokaiseen seuraavaan buildiin, ja jokainen build, jossa inkrementaalinen kääntäminen on kytketty pois päältä, mitätöi inkrementaaliset välimuistit.

Huomaa, että ensimmäinen build ei missään tapauksessa ole inkrementaalinen.

Gradlen rakennusvälimuistin tuki

Kotlin-liitännäinen tukee Gradlen rakennusvälimuistia, joka tallentaa rakennustulokset uudelleenkäyttöä varten tulevissa rakennuksissa.

Jos haluat poistaa välimuistitiedostot käytöstä kaikkien Kotlin-tehtävien osalta, aseta järjestelmäominaisuuden lipputunnus kotlin.caching.enabled arvoon false (suorita rakennustyö argumentilla -Dkotlin.caching.enabled=false).

Jos käytät kapt:ia, huomioi, että kapt:n annotaatioiden käsittelytehtävät eivät ole oletusarvoisesti välimuistissa. Voit kuitenkin ottaa niiden välimuistitallennuksen käyttöön manuaalisesti.

Gradlen konfiguraatiovälimuistituki

Konfiguraatiovälimuisti on saatavilla Gradle 6.5:ssä ja uudemmissa versioissa kokeellisena ominaisuutena.Voit tarkistaa Gradlen julkaisut-sivulta, onko se nostettu stabiiliksi.

Kotlin-lisäosa tukee Gradlen konfiguraatiovälimuistia,joka nopeuttaa rakentamisprosessia käyttämällä uudelleen konfigurointivaiheen tuloksia.

Katso Gradlen dokumentaatiota saadaksesi tietää, miten konfiguraatiovälimuisti otetaan käyttöön. Kun otat konfiguraatiovälimuistiominaisuuden käyttöön, Kotlin Gradle-lisäosa alkaa käyttää sitä.

Kääntäjän asetukset

Kääntäjän lisäasetusten määrittämiseen voit käyttää Kotlin-kääntämistehtävän kotlinOptions-ominaisuutta.

JVM:ää kohdennettaessa tehtäviä kutsutaan tuotantokoodin osalta nimellä compileKotlin ja testikoodin osalta compileTestKotlin. Mukautettujen lähdekoodisarjojen tehtäviä kutsutaan compile<Name>Kotlin-kuvion mukaisesti.

Tehtävien nimet Android-projekteissa sisältävät rakentamisvaihtoehtojen nimet ja noudattavat mallia compile<BuildVariant>Kotlin, esimerkiksi compileDebugKotlin, compileReleaseUnitTestKotlin.

Kohdennettaessa JavaScriptiä tehtäviä kutsutaan compileKotlinJs– ja compileTestKotlinJs-nimellä ja mukautettuja lähdekoodisarjoja varten compile<Name>KotlinJs-nimellä.

Käyttämällä yksittäisen tehtävän nimeä konfiguroidaksesi yksittäisen tehtävän nimeä. Esimerkkejä:

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

Huomaa, että Gradle Kotlin DSL:n kanssa tehtävä kannattaa hakea ensin projektin tasks:stä.

Käytä JS- ja Common-kohteille vastaavasti tyyppejä Kotlin2JsCompile ja KotlinCompileCommon.

Projektin kaikki Kotlin-kääntämistehtävät on myös mahdollista määrittää:

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

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

Kokonaisuudessaan Gradle-tehtävien asetukset ovat seuraavat:

Attribuutit yhteisiä JVM:lle, JS, ja JS DCE

JVM:lle ja JS:lle yhteiset attribuutit

Attribuutit. JVM-kohtaiset

.

JS-kohtaiset attribuutit

.

yhteydessä

Dokumentaation generoiminen

Luo dokumentaation Kotlin-projekteille, käytä Dokka;katso Dokka README:stä konfigurointiohjeet. Dokka tukee sekakielisiä projekteja ja voi tuottaa tulosteen useissamuodoissa, mukaan lukien standardi JavaDoc.

OSGi

OSGi-tuen osalta katso Kotlin OSGi -sivu.

Käyttäessäsi Gradle Kotlin DSL:ää

Käyttäessäsi Gradle Kotlin DSL:ää, sovita Kotlin-liitännäiset lohkolla plugins { ... }. Jos sovellat niitä sen sijaan apply { plugin(...) }-lohkolla, saatat kohdata ratkaisemattomia viittauksia Gradle Kotlin DSL:n tuottamiin laajennuksiin. Voit ratkaista tämän kommentoimalla virheelliset käytöt pois, suorittamalla Gradle-tehtävän kotlinDslAccessorsSnapshot, poistamalla käytöt takaisin ja suorittamalla rakentamisen uudelleen tai tuomalla projektin uudelleen IDE:hen.