Używanie Gradle

Edytuj stronę

Aby zbudować projekt Kotlin za pomocą Gradle, należy zastosować wtyczkę Kotlin Gradle do swojego projektu i skonfigurować zależności.

Wtyczka i wersje

Zastosuj wtyczkę Kotlin Gradle za pomocą Gradle plugins DSL.

Wtyczka Kotlin Gradle 1.4.30 działa z Gradle 5.4 i późniejszymi. The kotlin-multiplatform pluginrequires Gradle 6.0 or later.

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

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

Placeholder <...> należy zastąpić jedną z nazw wtyczek, które można znaleźć w dalszych sekcjach.

Ukierunkowanie na wiele platform

Projekty ukierunkowane na wiele platform, zwane projektami wieloplatformowymi, wymagają wtyczki kotlin-multiplatform. Dowiedz się więcej o tej wtyczce.

Wtyczka kotlin-multiplatform działa z Gradle 6.0 lub nowszym.

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

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

Ukierunkowanie na JVM

Aby ukierunkować projekt na JVM, zastosuj wtyczkę Kotlin JVM.

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

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

Wtyczka version powinna być dosłowna w tym bloku i nie może być zastosowana z innego skryptu budującego.

Alternatywnie, możesz użyć starszego apply plugin podejścia:

apply plugin: 'kotlin'

Nie zaleca się stosowania wtyczek Kotlin z apply w Gradle Kotlin DSL – zobacz dlaczego.

Źródła Kotlin i Java

Źródła Kotlin mogą być przechowywane ze źródłami Java w tym samym folderze, lub umieszczone w różnych folderach. Domyślną konwencją jest używanie różnych folderów:

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

Odpowiednia właściwość sourceSets powinna być zaktualizowana, jeśli nie używamy domyślnej konwencji:

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

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

Celowanie na JavaScript

Gdy celujemy tylko w JavaScript, użyj wtyczki kotlin-js. Dowiedz się więcej

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

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

Źródła Kotlin i Java

Ta wtyczka działa tylko dla plików Kotlin, więc zaleca się przechowywanie plików Kotlin i Java osobno (w przypadku, gdy projekt zawiera pliki Java). Jeśli nie przechowujesz ich osobno, określ folder źródłowy w bloku sourceSets:

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

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

Targeting Android

Zaleca się używanie Android Studio do tworzenia aplikacji na Androida. Dowiedz się, jak korzystać z wtyczki Android Gradle.

Konfigurowanie zależności

Aby dodać zależność od biblioteki, ustaw zależność wymaganego typu (na przykład implementation) w bloku dependencies zestawów źródłowych 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") } } }}

Alternatywnie, można ustawić zależności na najwyższym poziomie.

Typy zależności

Wybierz typ zależności w oparciu o swoje wymagania.

Zależność od biblioteki standardowej

Zależność od biblioteki standardowej (stdlib) w każdym zestawie źródeł jest dodawana automatycznie. Wersja biblioteki standardowej jest taka sama, jak wersja wtyczki Kotlin Gradle.

W przypadku zestawów źródłowych specyficznych dla platformy, używany jest odpowiedni wariant biblioteki specyficzny dla platformy, podczas gdy wspólna biblioteka standardowa jest dodawana do reszty. Wtyczka Kotlin Gradle wybierze odpowiednią bibliotekę standardową JVM w zależności od kotlinOptions.jvmTarget opcji kompilatora twojego skryptu budowania Gradle.

Jeśli zadeklarujesz zależność biblioteki standardowej jawnie (na przykład, jeśli potrzebujesz innej wersji), wtyczka Kotlin Gradle nie zastąpi jej lub doda drugą bibliotekę standardową.

Jeśli w ogóle nie potrzebujesz biblioteki standardowej, możesz dodać flagę opt-out do gradle.properties:

kotlin.stdlib.default.dependency=false

Ustawianie zależności od bibliotek testowych

Dostępne jest API kotlin.test do testowania różnych projektów Kotlin.

Dodaj odpowiednie zależności na bibliotekach testowych:

• Dla commonTest, dodaj zależności kotlin-test-common i kotlin-test-annotations-common.
• Dla celów JVM, użyj kotlin-test-junit lub kotlin-test-testng dla odpowiedniej implementacji asertera i mapowania adnotacji.
• Dla celów Kotlin/JS, dodaj kotlin-test-js jako zależność testową.

Cele Kotlin/Native nie wymagają dodatkowych zależności testowych, a implementacje kotlin.test API są wbudowane.

Możesz użyć skrótu dla zależności od modułu Kotlin, na przykład, kotlin(„test”) dla „org.jetbrains.kotlin:kotlin-test”.

Ustaw zależność od biblioteki kotlinx

Jeśli używasz biblioteki kotlinx i potrzebujesz zależności specyficznej dla platformy, możesz użyć specyficznych dla platformy wariantów bibliotek z przyrostkami takimi jak -jvm lub -js, na przykład kotlinx-coroutines-core-jvm. Zamiast tego można również użyć nazwy bazowej artefaktu biblioteki – kotlinx-coroutines-core.

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

Jeśli używasz biblioteki wieloplatformowej i potrzebujesz zależności od współdzielonego kodu, ustaw zależność tylko raz we współdzielonym zestawie źródłowym. Użyj nazwy artefaktu bazowej biblioteki, takiej jak kotlinx-coroutines-core lub ktor-client-core.

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

Ustaw zależności na najwyższym poziomie

Alternatywnie można określić zależności na najwyższym poziomie z nazwami konfiguracji według wzorca <sourceSetName><DependencyType>. Jest to pomocne w przypadku niektórych wbudowanych zależności Gradle, takich jak gradleApi(), localGroovy() lub gradleTestKit(), które nie są dostępne w DSL zależności zestawów źródłowych.

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

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

Przetwarzanie adnotacji

Kotlin obsługuje przetwarzanie adnotacji za pomocą narzędzia Kotlin do przetwarzania adnotacji kapt.

Kompilacja przyrostowa

Wtyczka Kotlin Gradle obsługuje kompilację przyrostową. Kompilacja przyrostowa śledzi zmiany plików źródłowych pomiędzy kompilacjami, więc tylko pliki dotknięte tymi zmianami będą kompilowane.

Kompilacja przyrostowa jest obsługiwana dla projektów Kotlin/JVM i Kotlin/JS i jest domyślnie włączona od Kotlin 1.1.1.

Jest kilka sposobów na wyłączenie tego ustawienia:

• Dodaj następującą linię do pliku gradle.properties lub local.properties:
  • kotlin.incremental=false dla projektów Kotlin/JVM
  • kotlin.incremental.js=false dla projektów Kotlin/JS

• Jako parametru wiersza poleceń użyj -Pkotlin.incremental=false lub -Pkotlin.incremental.js=false.

  Zauważ, że w tym przypadku parametr powinien być dodawany do każdej kolejnej kompilacji, a każda kompilacja z wyłączoną kompilacją przyrostową unieważnia przyrostowe pamięci podręczne.

Zauważ, że pierwsza kompilacja nie jest przyrostowa w każdym przypadku.

Obsługa buforowania kompilacji Gradle

Wtyczka Kotlin obsługuje buforowanie kompilacji Gradle, które przechowuje dane wyjściowe kompilacji do ponownego użycia w przyszłych kompilacjach.

Aby wyłączyć buforowanie dla wszystkich zadań Kotlina, ustaw flagę właściwości systemowej kotlin.caching.enabled na false (uruchom kompilację z argumentem -Dkotlin.caching.enabled=false).

Jeśli używasz kapt, zauważ, że zadania przetwarzania adnotacji kapt nie są domyślnie buforowane. Można jednak włączyć dla nich buforowanie ręcznie.

Obsługa pamięci podręcznej konfiguracji Gradle

Pamięć podręczna konfiguracji jest dostępna w Gradle 6.5 i nowszych jako funkcja eksperymentalna.Możesz sprawdzić stronę wydań Gradle, aby zobaczyć, czy została ona awansowana do wersji stabilnej.

Wtyczka Kotlin obsługuje pamięć podręczną konfiguracji Gradle, która przyspiesza proces budowania poprzez ponowne wykorzystanie wyników fazy konfiguracji.

Zobacz dokumentację Gradle, aby dowiedzieć się, jak włączyć pamięć podręczną konfiguracji. Po włączeniu funkcji pamięci podręcznej konfiguracji, wtyczka Kotlin Gradle zacznie jej używać.

Opcje kompilatora

Aby określić dodatkowe opcje kompilacji, użyj właściwości kotlinOptions zadania kompilacji Kotlin.

Gdy celujemy w JVM, zadania nazywają się compileKotlin dla kodu produkcyjnego i compileTestKotlin dla kodu testowego. Zadania dla niestandardowych zestawów źródeł są nazywane odpowiednio do wzorca compile<Name>Kotlin.

Nazwy zadań w Android Projects zawierają nazwy wariantów budowania i są zgodne ze wzorcem compile<BuildVariant>Kotlin, na przykład compileDebugKotlin, compileReleaseUnitTestKotlin.

W przypadku kierowania na JavaScript zadania są nazywane odpowiednio compileKotlinJs i compileTestKotlinJs oraz compile<Name>KotlinJs dla niestandardowych zestawów źródeł.

Aby skonfigurować pojedyncze zadanie, należy użyć jego nazwy. Przykłady:

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

Zauważ, że w przypadku Gradle Kotlin DSL należy najpierw pobrać zadanie z tasks projektu.

Użyj odpowiednio typów Kotlin2JsCompile i KotlinCompileCommon dla celów JS i Common.

Możliwe jest również skonfigurowanie wszystkich zadań kompilacji Kotlina w projekcie:

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

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

Pełna lista opcji dla zadań Gradle jest następująca:

Atrybuty wspólne dla JVM, JS, i JS DCE

Atrybuty wspólne dla JVM i JS

Atrybuty specyficzne dla JVM

Atrybuty specyficzne dla JS

.

.

Generowanie dokumentacji

Do generowania dokumentacji dla projektów Kotlin, użyj Dokka;instrukcje konfiguracji znajdują się w dokka README. Dokka obsługuje projekty mieszane językowo i może generować dane wyjściowe w wielu formatach, w tym w standardowym JavaDoc.

OSGi

W sprawie wsparcia OSGi zobacz stronę Kotlin OSGi.

Usługiwanie Gradle Kotlin DSL

Gdy używasz Gradle Kotlin DSL, zastosuj wtyczki Kotlin za pomocą bloku plugins { ... }. Jeśli zastosujesz je za pomocą apply { plugin(...) } zamiast tego, możesz napotkać nierozwiązane odniesienia do rozszerzeń wygenerowanych przez Gradle Kotlin DSL. Aby rozwiązać ten problem, możesz wykomentować błędne użycia, uruchomić zadanie Gradle kotlinDslAccessorsSnapshot, a następnie odkomentować je z powrotem i ponownie uruchomić kompilację lub ponownie zaimportować projekt do IDE.