Usare Gradle

Modifica pagina

Per costruire un progetto Kotlin con Gradle, dovresti applicare il plugin Kotlin Gradle al tuo progetto e configurare le dipendenze.

Plugin e versioni

Applica il plugin Kotlin Gradle usando il Gradle plugins DSL.

Il plugin Kotlin Gradle 1.4.30 funziona con Gradle 5.4 e successivi. Il plugin kotlin-multiplatformrichiede Gradle 6.0 o successivo.

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

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

Il segnaposto <...> dovrebbe essere sostituito con uno dei nomi dei plugin che possono essere trovati in altre sezioni.

Targeting piattaforme multiple

I progetti che mirano a piattaforme multiple, chiamati progetti multipiattaforma, richiedono il plugin kotlin-multiplatform. Per saperne di più sul plugin.

Il plugin kotlin-multiplatform funziona con Gradle 6.0 o successivo.

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

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

Targeting della JVM

Per indirizzare la JVM, applica il plugin Kotlin JVM.

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

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

Il version dovrebbe essere letterale in questo blocco, e non può essere applicato da un altro script di build.

In alternativa, puoi usare il vecchio approccio apply plugin:

apply plugin: 'kotlin'

Non è raccomandato applicare i plugin Kotlin con apply in Gradle Kotlin DSL – vedi perché.

Sorgenti Kotlin e Java

I sorgenti Kotlin possono essere memorizzati con quelli Java nella stessa cartella, o messi in cartelle diverse. La convenzione predefinita è di usare cartelle diverse:

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

La proprietà sourceSets corrispondente dovrebbe essere aggiornata se non si usa la convenzione predefinita:

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

Quando si punta solo a JavaScript, usare il plugin kotlin-js. Per saperne di più

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

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

Sorgenti Kotlin e Java

Questo plugin funziona solo per i file Kotlin quindi si raccomanda di conservare i file Kotlin e Java separatamente (nel caso il progetto contenga file Java). Se non li conservi separatamente, specifica la cartella dei sorgenti nel blocco sourceSets:

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

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

Targeting Android

Si raccomanda di usare Android Studio per creare applicazioni Android. Impara come usare il plugin Android Gradle.

Configurare le dipendenze

Per aggiungere una dipendenza da una libreria, imposta la dipendenza del tipo richiesto (per esempio, implementation) nel blocco dependencies del DSL dei set di sorgenti.

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

In alternativa, puoi impostare le dipendenze al livello superiore.

Tipi di dipendenza

Scegli il tipo di dipendenza in base alle tue esigenze.

Dipendenza dalla libreria standard

Una dipendenza da una libreria standard (stdlib) in ogni set di sorgenti viene aggiunta automaticamente. La versione della libreria standard è la stessa del plugin Kotlin Gradle.

Per i set di sorgenti specifici della piattaforma, viene usata la variante corrispondente della libreria specifica della piattaforma, mentre una libreria standard comune viene aggiunta al resto. Il plugin Kotlin Gradle selezionerà la libreria standard JVM appropriata a seconda dell’opzione del compilatore kotlinOptions.jvmTarget del tuo script di compilazione Gradle.

Se dichiari una dipendenza della libreria standard esplicitamente (per esempio, se hai bisogno di una versione diversa), il plugin Kotlin Gradle non la sovrascriverà o aggiungerà una seconda libreria standard.

Se non hai affatto bisogno di una libreria standard, puoi aggiungere il flag di opt-out al gradle.properties:

kotlin.stdlib.default.dependency=false

Imposta dipendenze su librerie di test

L’API kotlin.test è disponibile per testare diversi progetti Kotlin.

Aggiungi le corrispondenti dipendenze sulle librerie di test:

• Per commonTest, aggiungi le dipendenze kotlin-test-common e kotlin-test-annotations-common.
• Per gli obiettivi JVM, usare kotlin-test-junit o kotlin-test-testng per la corrispondente implementazione dell’asseritore e la mappatura delle annotazioni.
• Per gli obiettivi Kotlin/JS, aggiungere kotlin-test-js come dipendenza di test.

Gli obiettivi Kotlin/Native non richiedono ulteriori dipendenze di test, e le implementazioni API kotlin.test sono integrate.

Puoi usare un’abbreviazione per una dipendenza da un modulo Kotlin, per esempio, kotlin(“test”) per “org.jetbrains.kotlin:kotlin-test”.

Imposta una dipendenza da una libreria kotlinx

Se usi una libreria kotlinx e hai bisogno di una dipendenza specifica della piattaforma, puoi usare varianti specifiche della piattaforma delle librerie con suffissi come -jvm o -js, per esempio, kotlinx-coroutines-core-jvm. Puoi anche usare il nome dell’artefatto base della libreria invece – kotlinx-coroutines-core.

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

Se usi una libreria multipiattaforma e hai bisogno di dipendere dal codice condiviso, imposta la dipendenza solo una volta nel set di sorgenti condivisi. Usa il nome dell’artefatto base della libreria, come kotlinx-coroutines-core o ktor-client-core.

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

Imposta le dipendenze al livello superiore

In alternativa, puoi specificare le dipendenze al livello superiore con i nomi di configurazione che seguono lo schema <sourceSetName><DependencyType>. Questo è utile per alcune dipendenze integrate di Gradle, come gradleApi(), localGroovy(), o gradleTestKit(), che non sono disponibili nel DSL delle dipendenze dei set di sorgenti.

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

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

Elaborazione delle annotazioni

Kotlin supporta l’elaborazione delle annotazioni tramite lo strumento di elaborazione delle annotazioni Kotlin kapt.

Compilazione incrementale

Il plugin Gradle Kotlin supporta la compilazione incrementale. La compilazione incrementale tiene traccia dei cambiamenti dei file sorgente tra una compilazione e l’altra in modo che solo i file interessati da questi cambiamenti vengano compilati.

La compilazione incrementale è supportata per i progetti Kotlin/JVM e Kotlin/JS ed è abilitata di default da Kotlin 1.1.1.

Ci sono diversi modi per disabilitare l’impostazione:

• Aggiungere la seguente linea al file gradle.properties o local.properties:
  • kotlin.incremental=false per Kotlin/JVM
  • kotlin.incremental.js=false per progetti Kotlin/JS

• Come parametro della riga di comando, usa -Pkotlin.incremental=false o -Pkotlin.incremental.js=false.

  Nota che in questo caso il parametro deve essere aggiunto ad ogni build successiva, e ogni build con compilazione incrementale disabilitata invalida le cache incrementali.

Nota che la prima build non è incrementale in ogni caso.

Supporto alla cache di build di Gradle

Il plugin Kotlin supporta la cache di build di Gradle che memorizza gli output di build per riutilizzarli nelle build future.

Per disabilitare la cache per tutti i task Kotlin, imposta il flag della proprietà di sistema kotlin.caching.enabled su false (esegui la build con l’argomento -Dkotlin.caching.enabled=false).

Se usi kapt, nota che i task di elaborazione delle annotazioni kapt non sono memorizzati nella cache per impostazione predefinita. Tuttavia, puoi abilitare la cache per loro manualmente.

Supporto alla cache di configurazione di Gradle

La cache di configurazione è disponibile in Gradle 6.5 e successivi come caratteristica sperimentale.Puoi controllare la pagina delle release di Gradle per vedere se è stata promossa a stabile.

Il plugin Kotlin supporta la cache di configurazione di Gradle, che velocizza il processo di compilazione riutilizzando i risultati della fase di configurazione.

Vedi la documentazione di Gradle per sapere come abilitare la cache di configurazione. Una volta abilitata la caratteristica della cache di configurazione, il plugin Gradle Kotlin inizierà ad usarla.

Opzioni del compilatore

Per specificare opzioni di compilazione aggiuntive, usa la proprietà kotlinOptions di un task di compilazione Kotlin.

Quando si punta alla JVM, i task sono chiamati compileKotlinper il codice di produzione e compileTestKotlinper il codice di test. I compiti per i set di sorgenti personalizzati sono chiamati secondo lo schema compile<Name>Kotlin.

I nomi dei compiti nei progetti Android contengono i nomi delle varianti di compilazione e seguono lo schema compile<BuildVariant>Kotlin, per esempio, compileDebugKotlin, compileReleaseUnitTestKotlin.

Quando si punta a JavaScript, i compiti sono chiamati rispettivamente compileKotlinJs e compileTestKotlinJs, e compile<Name>KotlinJs per i set di sorgenti personalizzati.

Per configurare un singolo compito, usa il suo nome. Esempi:

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

Nota che con Gradle Kotlin DSL, dovresti prima ottenere il task dal tasks del progetto.

Usa i tipi Kotlin2JsCompile e KotlinCompileCommon per gli obiettivi JS e Common, di conseguenza.

È anche possibile configurare tutti i task di compilazione di Kotlin nel progetto:

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

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

L’elenco completo delle opzioni per i task Gradle è il seguente:

Attributi comuni per JVM, JS, e JS DCE

Attributi comuni per JVM e JS

Attributi specifici per JVM

Attributi specifici per JS

Generare documentazione

Per generare documentazione per progetti Kotlin, utilizzare Dokka;fare riferimento al README di Dokka per le istruzioni di configurazione. Dokka supporta progetti in lingue miste e può generare output in formati multipli, incluso JavaDoc standard.

OSGi

Per il supporto OSGi vedi la pagina Kotlin OSGi.

Usare Gradle Kotlin DSL

Quando usi Gradle Kotlin DSL, applica i plugin Kotlin usando il blocco plugins { ... }. Se invece li applichi con apply { plugin(...) }, potresti incontrare riferimenti irrisolti alle estensioni generate da Gradle Kotlin DSL. Per risolverlo, puoi commentare gli usi errati, eseguire il task Gradle kotlinDslAccessorsSnapshot, poi scomporre di nuovo gli usi e rieseguire la compilazione o reimportare il progetto nell’IDE.