Použití Gradle - Programovací jazyk Kotlin

Edit Page

Chcete-li sestavit projekt Kotlin pomocí Gradle, měli byste na svůj projekt použít zásuvný modul Kotlin Gradle a nakonfigurovat závislosti.

Zásuvný modul a verze

Zásuvný modul Kotlin Gradle aplikujte pomocí zásuvných modulů Gradle DSL.

Zásuvný modul Kotlin Gradle 1.4.30 funguje s Gradle 5.4 a novějším. Zásuvný modul kotlin-multiplatformvyžaduje Gradle 6.0 nebo novější.

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

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

Zástupce <...> by měl být nahrazen jedním z názvů zásuvných modulů, které najdete v dalších částech.

Zaměření na více platforem

Projekty zaměřené na více platforem, tzv. multiplatformní projekty, vyžadují zásuvný modul kotlin-multiplatform. Další informace o tomto zásuvném modulu.

Zásuvný modul kotlin-multiplatform funguje s nástrojem Gradle 6.0 nebo novějším.

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

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

Cílení na JVM

Pro cílení na JVM použijte zásuvný modul Kotlin JVM.

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

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

V tomto bloku by měl být version doslovný a nelze jej použít z jiného sestavovacího skriptu.

Alternativně můžete použít starší přístup apply plugin:

apply plugin: 'kotlin'

Nedoporučuje se aplikovat zásuvné moduly Kotlin pomocí apply v Gradle Kotlin DSL – viz proč.

Zdroje Kotlin a Java

Zdroje Kotlin mohou být uloženy se zdroji Java ve stejné složce nebo umístěny do různých složek. Výchozí konvence je použití různých složek:

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

Pokud nepoužíváte výchozí konvenci, měla by být aktualizována příslušná vlastnost sourceSets:

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

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

Cílení na JavaScript

Pokud cílíte pouze na JavaScript, použijte zásuvný modul kotlin-js. Více informací

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

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

Zdroje Kotlinu a Javy

Tento zásuvný modul funguje pouze pro soubory Kotlinu, takže doporučujeme vést soubory Kotlinu a Javy odděleně (v případě, že projekt obsahuje soubory Javy). Pokud je neukládáte odděleně , zadejte složku se zdroji v bloku sourceSets:

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

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

Targeting Android

Pro vytváření aplikací pro Android se doporučuje používat aplikaci Android Studio. Naučte se používat zásuvný modul Android Gradle.

Konfigurace závislostí

Chcete-li přidat závislost na knihovně, nastavte závislost požadovaného typu (například implementation) v bloku dependencies zdrojových sad 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") } } }}

Alternativně můžete závislosti nastavit na nejvyšší úrovni.

Typy závislostí

Vyberte typ závislosti podle svých požadavků.

Typ	Popis	Kdy použít
`api`	Používá se během kompilace i za běhu a je exportován konzumentům knihovny.	Pokud je některý typ ze závislosti použit ve veřejném API aktuálního modulu, použijte závislost `api`.
`implementation`	Používá se během kompilace a za běhu pro aktuální modul, ale není vystaven pro kompilaci jiných modulů závislých na modulu se závislostí `implementace`.	Použije se pro závislosti potřebné pro vnitřní logiku modulu. Je-li modul koncovou aplikací, která není publikována, použijte místo `api`závislosti `implementation`.
`compileOnly`	Používá se pro kompilaci aktuálního modulu a není k dispozici za běhu ani při kompilaci jiných modulů.	Používá se pro API, které mají za běhu k dispozici implementaci třetí strany.
`runtimeOnly`	Dostupné za běhu, ale není viditelné během kompilace žádného modulu.

Závislost na standardní knihovně

Závislost na standardní knihovně (stdlib) v každé zdrojové sadě se přidává automaticky. Verze standardní knihovny je stejná jako verze zásuvného modulu Kotlin Gradle.

U zdrojových sad specifických pro danou platformu je použita odpovídající varianta knihovny specifická pro danou platformu, zatímco u ostatních je přidána běžná standardní knihovna. Zásuvný modul Kotlin Gradle vybere příslušnou standardní knihovnu JVM v závislosti na volbě kotlinOptions.jvmTargetkompilátoru skriptu sestavení Gradle.

Pokud deklarujete závislost na standardní knihovně explicitně (například pokud potřebujete jinou verzi), zásuvný modul Kotlin Gradle ji nepřepíše ani nepřidá druhou standardní knihovnu.

Pokud standardní knihovnu vůbec nepotřebujete, můžete přidat příznak opt-out do gradle.properties:

kotlin.stdlib.default.dependency=false

Nastavení závislostí na testovacích knihovnách

Pro testování různých projektů Kotlin je k dispozici kotlin.test API.

Přidejte odpovídající závislosti na testovacích knihovnách:

Pro commonTest přidejte závislosti kotlin-test-common a kotlin-test-annotations-common.
Pro cíle JVM použijte kotlin-test-junit nebo kotlin-test-testng pro odpovídající implementaci asserteru a mapování anotací.
Pro cíle Kotlin/JS přidejte kotlin-test-js jako testovací závislost.

Cíle Kotlin/Native nevyžadují další testovací závislosti a implementace kotlin.test API jsou vestavěné.

Pro závislost na modulu Kotlin můžete použít zkratku, například kotlin(„test“) pro „org.jetbrains.kotlin:kotlin-test“.

Nastavení závislosti na knihovně kotlinx

Pokud používáte knihovnu kotlinx a potřebujete závislost specifickou pro danou platformu, můžete použít varianty knihoven specifické pro danou platformu s příponami jako -jvm nebo -js, například kotlinx-coroutines-core-jvm. Místo toho můžete také použít název základního artefaktu knihovny – kotlinx-coroutines-core.

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

Pokud používáte multiplatformní knihovnu a potřebujete závislost na sdíleném kódu, nastavte závislost pouze jednou v sadě sdílených zdrojů. Použijte název základního artefaktu knihovny, například kotlinx-coroutines-core nebo ktor-client-core.

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

Zadejte závislosti na nejvyšší úrovni

Alternativně můžete zadat závislosti na nejvyšší úrovni s názvy konfigurace podle vzoru <sourceSetName><DependencyType>. To je užitečné pro některé integrované závislosti Gradle, například gradleApi(), localGroovy() nebo gradleTestKit(), které nejsou k dispozici v DSL závislostí zdrojových sad.

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

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

Zpracování anotací

Kotlin podporuje zpracování anotací prostřednictvím nástroje Kotlin annotation processing kapt.

Inkrementální kompilace

Zásuvný modul Kotlin Gradle podporuje inkrementální kompilaci. Inkrementální kompilace sleduje změny zdrojových souborů mezi sestaveními, takže by se kompilovaly pouze soubory, kterých se tyto změny týkají.

Inkrementální kompilace je podporována pro projekty Kotlin/JVM a Kotlin/JS a je ve výchozím nastavení povolena od verze Kotlin 1.1.1.

Existuje několik způsobů, jak toto nastavení zakázat:

Přidejte následující řádek do souboru gradle.properties nebo local.properties:
- kotlin.incremental=false pro projekty Kotlin/JVM
- kotlin.incremental.js=false pro projekty Kotlin/JS
Jako parametr příkazového řádku použijte -Pkotlin.incremental=false nebo -Pkotlin.incremental.js=false.

Všimněte si, že v tomto případě by měl být parametr přidán ke každému následujícímu sestavení a každé sestavení s vypnutou inkrementální kompilací znehodnotí inkrementální mezipaměť.

Všimněte si, že první sestavení není v žádném případě inkrementální.

Podpora mezipaměti sestavení Gradle

Zásuvný modul Kotlin podporuje mezipaměť sestavení Gradle, která ukládá výstupy sestavení pro opětovné použití v budoucích sestaveních.

Chcete-li vypnout ukládání do mezipaměti pro všechny úlohy Kotlin, nastavte příznak vlastnosti systému kotlin.caching.enabled na hodnotu false (spusťte sestavení s argumentem -Dkotlin.caching.enabled=false).

Pokud používáte kapt, všimněte si, že úlohy zpracování anotací kapt nejsou ve výchozím nastavení ukládány do mezipaměti. Můžete však jejich ukládání do mezipaměti povolit ručně.

Podpora konfigurační mezipaměti Gradle

Konfigurační mezipaměť je k dispozici ve verzi Gradle 6.5 a novější jako experimentální funkce, zda byla povýšena na stabilní, zjistíte na stránce s verzemi Gradle.

Zásuvný modul Kotlin podporuje konfigurační mezipaměť Gradle,která urychluje proces sestavování opakovaným použitím výsledků konfigurační fáze.

V dokumentaci Gradle se dozvíte, jak konfigurační mezipaměť zapnout. Jakmile funkci konfigurační mezipaměti povolíte, zásuvný modul Gradle Kotlin ji začne používat.

Možnosti kompilátoru

Pro zadání dalších možností kompilace použijte vlastnost kotlinOptions kompilační úlohy Kotlin.

Při cílení na JVM se úlohy nazývají compileKotlinpro produkční kód a compileTestKotlinpro testovací kód. Úlohy pro vlastní zdrojové sady se nazývají podle vzoru compile<Name>Kotlin.

Jména úloh v projektech Android obsahují názvy variant sestavení a řídí se vzorem compile<BuildVariant>Kotlin, například compileDebugKotlin, compileReleaseUnitTestKotlin.

Při cílení na JavaScript se úlohy nazývají compileKotlinJs, respektive compileTestKotlinJs, a compile<Name>KotlinJs pro vlastní zdrojové sady.

Chcete-li konfigurovat jednu úlohu, použijte její název. Příklady:

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

Poznamenejte, že v případě Gradle Kotlin DSL byste měli nejprve získat úlohu z tasks projektu.

Pro cíle JS a Common použijte odpovídajícím způsobem typy Kotlin2JsCompile a KotlinCompileCommon.

V projektu je také možné nakonfigurovat všechny úlohy kompilace Kotlin:

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

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

Úplný seznam možností pro úlohy Gradle je následující:

Atributy společné pro JVM, JS, a JS DCE

Název	Popis	Možné hodnoty	Výchozí hodnota
`allWarningsAsErrors`	Hlásit chybu, pokud se vyskytnou nějaké. varování		false
`suppressWarnings`	Generovat žádná varování		false
`verbose`	Povolit slovní výstup protokolování	.	false
`freeCompilerArgs`	Seznam dalších argumentů kompilátoru

Atributy společné pro JVM a JS

Atributy. specifické pro JVM

Název	Popis	Možné hodnoty	Výchozí hodnota
`javaParameters`	Generování metadat pro Javu 1.8 reflexe na parametry metod		false
`jdkHome`	Zařadit vlastní JDK ze zadaného umístění do. classpath místo výchozího JAVA_HOME
`jvmTarget`	Cílová verze generovaného bytového kódu JVM	„1.6“, „1.8“, „9“, „10“, „11“, „12“, „13“, „14“, „15“	„1.6“
`noJdk`	Nezařazovat automaticky běhové prostředí jazyka Java do cesty tříd		false
`noReflect`	Nezařazovat automaticky odraz jazyka Kotlin do cesty tříd classpath		true
`noStdlib`	Nezařazovat automaticky Kotlin/JVM stdlib a Kotlin reflection do classpath		true
`useIR`	Použít IR backend		false

Atributy specifické pro JS

Název	Popis	Možné hodnoty	Přednastavená hodnota
`friendModulesDisabled`	Zakázat export interní deklarace		false
`main`	Určit, zda má být `main`funkce při provedení zavolána	„call“, „noCall“	„call“
`metaInfo`	Generovat .meta.js a .kjsm soubory s metadaty. Slouží k vytvoření knihovny		true
`moduleKind`	Druh JS modulu generovaného kompilátorem	„umd“, „commonjs“, „amd“, „plain“	„umd“
`noStdlib`	Nezařazovat automaticky výchozí Kotlin/JS stdlib do kompilačních závislostí		true
`outputFile`	Destination *.js soubor pro výsledek kompilace		„<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js“
`sourceMap`	Generovat zdrojovou mapu		true
`sourceMapEmbedSources`	Vložit zdrojové soubory do zdrojové mapy	„nikdy“, „vždy“, „inlining“
`sourceMapPrefix`	Přidat zadanou předponu k cestám v mapě zdrojů
`target`	Generovat JS soubory pro konkrétní verzi ECMA	„v5“	„v5“
`typedArrays`	Překládat primitivní pole na typovaná pole JS		true

Generování dokumentace

Pro generování dokumentace pro projekty Kotlin, použijte Dokka;Pokyny pro konfiguraci naleznete v README aplikace Dokka. Dokka podporuje projekty ve smíšených jazycích a může generovat výstup ve více formátech, včetně standardního JavaDoc.

OSGi

Pro podporu OSGi viz stránka Kotlin OSGi.

Používání Gradle Kotlin DSL

Při použití Gradle Kotlin DSL použijte zásuvné moduly Kotlin pomocí bloku plugins { ... }. Pokud je místo toho aplikujete pomocí apply { plugin(...) }, můžete se setkat s nevyřešenými odkazy na rozšíření generovaná pomocí Gradle Kotlin DSL. Chcete-li to vyřešit, můžete chybná použití zakomentovat, spustit úlohu Gradle kotlinDslAccessorsSnapshot, pak použití opět odkomentovat a znovu spustit sestavení nebo projekt znovu importovat do IDE.