Szerkesztés
A Kotlin projekt Gradle segítségével történő építéséhez a Kotlin Gradle bővítményt kell a projektre alkalmazni és a függőségeket konfigurálni.
- Plugin és verziók
- Targeting multiple platforms
- A JVM célzása
- Kotlin és Java források
- Célzott JavaScript
- Kotlin és Java források
- Targeting Android
- Függőségek beállítása
- Függőségi típusok
- Függés a szabványos könyvtárra
- Tesztkönyvtárak függőségének beállítása
- Függőség beállítása egy kotlinx könyvtárra
- Függőségek beállítása legfelső szinten
- Jegyzetfeldolgozás
- Inkrementális fordítás
- Gradle build cache támogatása
- Gradle konfigurációs gyorsítótár támogatása
- Compiler options
- A JVM, JS közös attribútumai, és JS DCE
- A JVM és JS közös attribútumai
- Attribútumok. JVM-specifikus
- A JS-re jellemző attribútumok
- Dokumentáció generálása
- OSGi
- A Gradle Kotlin DSL
Plugin és verziók
A Kotlin Gradle plugint a Gradle plugins DSL segítségével alkalmazza.
A Kotlin Gradle plugin 1.4.30 a Gradle 5.4 és újabb verziókkal működik. A kotlin-multiplatform pluginhoz a Gradle 6.0 vagy újabb verziója szükséges.
plugins { id 'org.jetbrains.kotlin.<...>' version '1.4.30'}plugins { kotlin("<...>") version "1.4.30"}A <...> helyőrzőt a további szakaszokban található plugin nevek valamelyikével kell helyettesíteni.
Targeting multiple platforms
A több platformot megcélzó, úgynevezett multiplatform projektekhez a kotlin-multiplatform plugin szükséges. Tudjon meg többet a bővítményről.
A
kotlin-multiplatformbővítmény a Gradle 6.0 vagy újabb verzióval működik.
plugins { id 'org.jetbrains.kotlin.multiplatform' version '1.4.30'}plugins { kotlin("multiplatform") version "1.4.30"}A JVM célzása
A JVM célzásához alkalmazza a Kotlin JVM bővítményt.
plugins { id "org.jetbrains.kotlin.jvm" version "1.4.30"}plugins { kotlin("jvm") version "1.4.30"}A version ebben a blokkban szó szerint kell lennie, és nem alkalmazható más build scriptből.
Alternatívaként használhatja a régebbi apply plugin megközelítést:
apply plugin: 'kotlin'A Gradle Kotlin DSL-ben nem ajánlott a apply Kotlin bővítmények apply alkalmazásával – lásd miért.
Kotlin és Java források
A Kotlin források tárolhatók a Java forrásokkal egy mappában, vagy különböző mappákba helyezhetők. Az alapértelmezett konvenció a különböző mappák használata:
project - src - main (root) - kotlin - javaA megfelelő sourceSets tulajdonságot kell frissíteni, ha nem az alapértelmezett konvenciót használjuk:
sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' main.java.srcDirs += 'src/main/myJava'}sourceSets.main { java.srcDirs("src/main/myJava", "src/main/myKotlin")}Célzott JavaScript
Ahol csak JavaScriptet célozunk, használjuk a kotlin-js bővítményt. További információ
plugins { id 'org.jetbrains.kotlin.js' version '1.4.30'}plugins { kotlin("js") version "1.4.30"}Kotlin és Java források
Ez a plugin csak Kotlin fájlokra működik, ezért ajánlott a Kotlin és Java fájlokat külön tartani (amennyiben a projekt Java fájlokat tartalmaz). Ha nem tárolja őket külön , adja meg a forrásmappát a sourceSets blokkban:
kotlin { sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' }}kotlin { sourceSets.apply { kotlin.srcDir("src/main/myKotlin") }}Targeting Android
Android alkalmazások készítéséhez ajánlott az Android Studio használata. Ismerje meg az Android Gradle plugin használatát.
Függőségek beállítása
A függőség hozzáadásához egy könyvtár függőségét a forráskészlet DSL dependencies blokkjában állítsa be a szükséges típusú függőséget (például implementation).
kotlin { sourceSets { val commonMain by getting { dependencies { implementation("com.example:my-library:1.0") } } }}Alternatívaként a függőségeket felső szinten is beállíthatja.
Függőségi típusok
A függőségi típus kiválasztása a követelmények alapján.
| Type | Description | When to use |
|---|---|---|
api |
A fordítás során és futásidőben is használjuk, és a könyvtárfogyasztóknak exportáljuk. | Ha az aktuális modul nyilvános API-jában a függőség bármelyik típusa használatos, használjon api függőséget. |
implementation |
A fordítás során és futásidőben az aktuális modul számára használatos, de a `implementációs` függőséggel rendelkező modultól függő más modulok fordításakor nem kerül kiállításra. |
A modul belső logikájához szükséges függőségek esetén használja. Ha a modul egy nem publikált végponti alkalmazás, akkor a |
compileOnly |
Az aktuális modul fordításához használatos, és sem futásidőben, sem más modulok fordítása során nem áll rendelkezésre. | Az olyan API-k esetében használható, amelyeknek futásidőben elérhető egy harmadik féltől származó implementációja. |
runtimeOnly |
Futásidőben elérhető, de egyik modul fordítása során sem látható. |
Függés a szabványos könyvtárra
A szabványos könyvtár függősége (stdlib) minden forráskészlethez automatikusan hozzáadódik. A szabványos könyvtár verziója megegyezik a Kotlin Gradle plugin verziójával.
A platform-specifikus forráskészletek esetében a könyvtár megfelelő platform-specifikus változata kerül felhasználásra, míg a többihez egy közös szabványos könyvtár kerül hozzáadásra. A Kotlin Gradle plugin a megfelelő JVM szabványos könyvtárat választja ki a Gradle build script kotlinOptions.jvmTarget fordítói opciójától függően.
Ha explicit módon deklarál egy szabványos könyvtárfüggőséget (például ha más verzióra van szüksége), a Kotlin Gradle plugin nem írja felül azt, és nem ad hozzá egy második szabványos könyvtárat.
Ha egyáltalán nincs szüksége szabványos könyvtárra, akkor a gradle.properties-hoz hozzáadhatja az opt-out jelzőt:
kotlin.stdlib.default.dependency=falseTesztkönyvtárak függőségének beállítása
A kotlin.test API különböző Kotlin projektek teszteléséhez áll rendelkezésre.
Adja hozzá a megfelelő függőségeket a tesztkönyvtárakhoz:
- A
commonTestesetében adja hozzá akotlin-test-commonéskotlin-test-annotations-commonfüggőségeket. - A JVM célokhoz használja a
kotlin-test-junitvagy akotlin-test-testngmegfelelő asserter implementációt és az annotációk leképezését. - A Kotlin/JS célokhoz adja hozzá a
kotlin-test-jstesztfüggőséget.
A Kotlin/Native célokhoz nincs szükség további tesztfüggőségekre, és a kotlin.test API implementációk beépítettek.
Egy Kotlin-modul függőségére használhat rövidítést, például kotlin(“test”) az “org.jetbrains.kotlin:kotlin-test”-re.
Függőség beállítása egy kotlinx könyvtárra
Ha egy kotlinx könyvtárat használ, és szüksége van egy platform-specifikus függőségre, használhatja a könyvtárak platform-specifikus változatait olyan utótagokkal, mint -jvm vagy -js, például kotlinx-coroutines-core-jvm. Használhatja helyette a könyvtár alap artifact nevét is – kotlinx-coroutines-core.
kotlin { sourceSets { jvmMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.2' } } }}Ha többplatformos könyvtárat használ, és szüksége van a megosztott kódtól való függésre, a függőséget csak egyszer állítsa be a megosztott forráskészletben. Használja a könyvtár alap artifact nevét, például kotlinx-coroutines-core vagy ktor-client-core.
kotlin { sourceSets { commonMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.2' } } }}Függőségek beállítása legfelső szinten
Alternatívaként megadhatja a függőségeket legfelső szinten a <sourceSetName><DependencyType> mintát követő konfigurációs nevekkel. Ez hasznos néhány Gradle beépített függőség esetében, mint például gradleApi(), localGroovy() vagy gradleTestKit(), amelyek nem állnak rendelkezésre a forráskészlet függőségi DSL-ben.
dependencies { "commonMainImplementation"("com.example:my-library:1.0")}Jegyzetfeldolgozás
A Kotlin támogatja a jegyzetfeldolgozást a Kotlin jegyzetfeldolgozó eszközzel kapt.
Inkrementális fordítás
A Kotlin Gradle plugin támogatja az inkrementális fordítást. Az inkrementális fordítás nyomon követi a forrásfájlok változásait a buildek között, így csak az ezen változások által érintett fájlok kerülnek lefordításra.
Az inkrementális fordítás támogatott a Kotlin/JVM és Kotlin/JS projektek esetében, és alapértelmezés szerint a Kotlin 1.1.1 óta engedélyezve van.
A beállítás letiltásának több módja is van:
- Adja hozzá a következő sort a
gradle.propertiesvagylocal.propertiesfájlhoz:-
kotlin.incremental=falseKotlin/JVM -
kotlin.incremental.js=falseKotlin/JS projektek
-
-
A parancssori paraméterként használja a
-Pkotlin.incremental=falsevagy-Pkotlin.incremental.js=falseparamétert.Megjegyezzük, hogy ebben az esetben a paramétert minden további buildhez hozzá kell adni, és minden olyan build, amelynél az inkrementális fordítás le van tiltva, érvényteleníti az inkrementális gyorsítótárakat.
Megjegyezzük, hogy az első build semmiképpen sem inkrementális.
Gradle build cache támogatása
A Kotlin bővítmény támogatja a Gradle build cache-t, amely tárolja a build kimeneteit a későbbi buildek során történő újrafelhasználás céljából.
A cache letiltásához minden Kotlin feladat esetében állítsa a kotlin.caching.enabled rendszer tulajdonság flag-et false-ra (futtassa a buildet a -Dkotlin.caching.enabled=false argumentummal).
Ha kapt-ot használ, vegye figyelembe, hogy a kapt annotation feldolgozási feladatok alapértelmezés szerint nem kerülnek cache-be. Azonban manuálisan engedélyezheti a gyorsítótárazást számukra.
Gradle konfigurációs gyorsítótár támogatása
A konfigurációs gyorsítótár a Gradle 6.5 és újabb verziókban kísérleti funkcióként érhető el.A Gradle releases oldalán megnézheti, hogy a funkciót stabilra léptették-e elő.
A Kotlin plugin támogatja a Gradle konfigurációs gyorsítótárát,amely a konfigurációs fázis eredményeinek újrafelhasználásával felgyorsítja az építési folyamatot.
A Gradle dokumentációból megtudhatja, hogyan engedélyezheti a konfigurációs gyorsítótárat. A konfigurációs gyorsítótár funkció engedélyezése után a Kotlin Gradle plugin elkezdi használni azt.
Compiler options
A további fordítási opciók megadásához használja a Kotlin fordítási feladat kotlinOptions tulajdonságát.
A JVM megcélzásakor a feladatok neve compileKotlin a termelési kódhoz és compileTestKotlin a tesztkódhoz. Az egyéni forráskészletekhez tartozó feladatokat a compile<Name>Kotlin mintának megfelelően hívjuk.
Az Android Projektekben a feladatok nevei tartalmazzák a build variánsok nevét, és a compile<BuildVariant>Kotlin mintát követik, például compileDebugKotlin, compileReleaseUnitTestKotlin.
A JavaScript célzása esetén a feladatok neve compileKotlinJs, illetve compileTestKotlinJs, az egyéni forráskészletek esetében pedig compile<Name>KotlinJs.
Egyetlen feladat konfigurálásához használjuk annak nevét. Példák:
compileKotlin { kotlinOptions.suppressWarnings = true}//orcompileKotlin { kotlinOptions { suppressWarnings = true }}Figyeljen arra, hogy a Gradle Kotlin DSL esetén a feladatot először a projekt tasks-ből kell megszereznie.
A JS és Common célokhoz ennek megfelelően a Kotlin2JsCompile és KotlinCompileCommon típusokat használja.
A projektben az összes Kotlin fordítási feladatot is beállíthatja:
tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { kotlinOptions { /*...*/ }}tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach { kotlinOptions { /*...*/ }}A Gradle feladatok beállításainak teljes listája a következő:
A JVM, JS közös attribútumai, és JS DCE
| Név | leírás | lehetséges értékek | alapértelmezett érték |
|---|---|---|---|
allWarningsAsErrors |
Hiba jelentése, ha vannak figyelmeztetések | false | |
suppressWarnings |
Nem generál figyelmeztetéseket | false | |
verbose |
Szöveges naplózási kimenet engedélyezése | . | false |
freeCompilerArgs |
A további fordítói argumentumok listája |
A JVM és JS közös attribútumai
Attribútumok. JVM-specifikus
| Név | leírás | lehetséges értékek | alapértelmezett érték | |
|---|---|---|---|---|
javaParameters |
Metaadatok generálása a Java 1 számára.8 reflection on method parameters | false | ||
jdkHome |
Inklimentálja az egyéni JDK-t a megadott helyről a classpath helyett az alapértelmezett JAVA_HOME | |||
jvmTarget |
A generált JVM bytecode célverziója | “1.6”, “1.8”, “9”, “10”, “11”, “12”, “13”, “14”, “15” | “1.6” | |
noJdk |
Ne vegye fel automatikusan a Java futtatási időt a classpathba | false | ||
noReflect |
Ne vegye fel automatikusan a Kotlin reflexiót a classpathba. classpath | true | ||
noStdlib |
Don’t automatically include the Kotlin/JVM stdlib and Kotlin reflection into the classpath | true | ||
useIR |
Az IR backend használata | false |
A JS-re jellemző attribútumok
| Név | leírás | lehető értékek | alapértelmezett érték |
|---|---|---|---|
friendModulesDisabled |
Belső deklaráció exportjának kikapcsolása | false | |
main |
Meghatározza, hogy a mainfüggvényt végrehajtáskor meg kell-e hívni |
“call”, “noCall” | “call” |
metaInfo |
Generálja .meta.js és .kjsm fájlokat metaadatokkal. Használja könyvtár létrehozásához | true | |
moduleKind |
A fordító által generált JS modul típusa | “umd”, “commonjs”, “amd”, “plain” | “umd” |
noStdlib |
Ne vegye fel automatikusan az alapértelmezett Kotlin/JS stdlib-et a fordítási függőségekbe | true | |
outputFile |
Cél *.js fájl a fordítás eredményének | “<buildDir>/js/packages/<projekt.név>/kotlin/<projekt.név>.js” | |
sourceMap |
Generate source map | true | |
sourceMapEmbedSources |
Embed source files into source map | “never”, “always”, “inlining” | |
sourceMapPrefix |
Add a megadott előtagot az elérési utakhoz a forrástérképben | ||
target |
JS fájlok generálása adott ECMA verzióhoz | “v5” | “v5” |
typedArrays |
Primitív tömbök fordítása JS tipizált tömbökké | true |
Dokumentáció generálása
Kotlin projektek dokumentációjának generálása, használja a Dokkát;Kérjük, olvassa el a Dokka README-jét a konfigurációs utasításokért. A Dokka támogatja a vegyes nyelvű projekteket, és többféle formátumban képes kimenetet generálni, beleértve a szabványos JavaDoc-ot is.
OSGi
Az OSGi támogatással kapcsolatban lásd a Kotlin OSGi oldalt.
A Gradle Kotlin DSL
A Gradle Kotlin DSL használata esetén a Kotlin bővítményeket a plugins { ... } blokk segítségével alkalmazza. Ha ehelyett a apply { plugin(...) } blokkal alkalmazza őket, előfordulhat, hogy a Gradle Kotlin DSL által generált bővítményekre vonatkozó megoldatlan hivatkozásokkal találkozik. Ezt úgy oldhatja meg, hogy kikommenteli a hibás felhasználásokat, lefuttatja a Gradle feladatot kotlinDslAccessorsSnapshot, majd visszakommenteli a felhasználásokat, és újra lefuttatja a buildet, vagy újra importálja a projektet az IDE-be.