Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Migracja konfiguracji kompilacji z Groovy do Kotlin

Wtyczka Androida do obsługi Gradle w wersji 4.0 dodała obsługę języka Kotlin w konfiguracji kompilacji Gradle jako zamiennika języka Groovy, języka programowania tradycyjnie używanego w plikach konfiguracji Gradle.

Do pisania skryptów Gradle preferowany jest Kotlin, a nie Groovy, ponieważ Kotlin jest bardziej czytelny i zapewnia lepsze sprawdzanie w czasie kompilacji oraz obsługę IDE.

Chociaż Kotlin oferuje obecnie lepszą integrację z edytorem kodu Android Studio w porównaniu z Groovy, kompilacje korzystające z Kotlina są zwykle wolniejsze niż kompilacje korzystające z Groovy, więc przy podejmowaniu decyzji o migracji weź pod uwagę wydajność kompilacji.

Na tej stronie znajdziesz podstawowe informacje o konwertowaniu plików kompilacji Gradle aplikacji na Androida z Groovy na Kotlina. Bardziej szczegółowy przewodnik po migracji znajdziesz w oficjalnej dokumentacji Gradle.

Oś czasu

Od wersji Android Studio Giraffe nowe projekty domyślnie używają do konfiguracji kompilacji języka Kotlin DSL (build.gradle.kts). Zapewnia to lepsze wrażenia podczas edytowania niż Groovy DSL (build.gradle) dzięki wyróżnianiu składni, uzupełnianiu kodu i nawigacji do deklaracji. Więcej informacji znajdziesz w podstawowych informacjach o Gradle Kotlin DSL.

Typowe terminy

Kotlin DSL: odnosi się głównie do wtyczki Androida do obsługi Gradle Kotlin DSL lub czasami do podstawowego Gradle Kotlin DSL.

W tym przewodniku po migracji terminy „Kotlin” i „Kotlin DSL” są używane zamiennie. Podobnie „Groovy” i „Groovy DSL” są używane zamiennie.

Nazwy plików skryptów

Rozszerzenia plików skryptów zależą od języka, w którym napisany jest plik kompilacji:

Pliki kompilacji Gradle napisane w języku Groovy mają rozszerzenie nazwy pliku .gradle.
Pliki kompilacji Gradle zapisane w języku Kotlin mają rozszerzenie nazwy pliku .gradle.kts.

Konwertowanie składni

Istnieją pewne ogólne różnice w składni między Groovy i Kotlinem, więc musisz zastosować te zmiany w skryptach kompilacji.

Dodaj nawiasy do wywołań metod

Groovy pozwala pominąć nawiasy w wywołaniach metod, podczas gdy Kotlin ich wymaga. Aby przenieść konfigurację, dodaj nawiasy do tego typu wywołań metod. Ten kod pokazuje, jak skonfigurować ustawienie w Groovy:

compileSdkVersion 30

Ten sam kod napisany w języku Kotlin:

compileSdkVersion(30)

Dodaj `=` do rozmów dotyczących projektu

Groovy DSL pozwala pominąć operator przypisania = podczas przypisywania właściwości, podczas gdy Kotlin go wymaga. Ten kod pokazuje, jak przypisać właściwości w Groovy:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Ten kod pokazuje, jak przypisać właściwości w języku Kotlin:

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Konwertowanie ciągów znaków

Oto różnice między ciągami znaków w Groovy i Kotlin:

Podwójne cudzysłowy w przypadku ciągów znaków: Groovy umożliwia definiowanie ciągów znaków za pomocą pojedynczych cudzysłowów, ale Kotlin wymaga podwójnych cudzysłowów.
Interpolacja ciągów znaków w wyrażeniach z kropkami: w Groovy możesz używać tylko prefiksu $ do interpolacji ciągów znaków w wyrażeniach z kropkami, ale Kotlin wymaga, aby wyrażenia z kropkami były ujęte w nawiasy klamrowe. Na przykład w Groovy możesz użyć $project.rootDir, jak pokazano w tym fragmencie kodu:
```
myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
```
Jednak w Kotlinie poprzedni kod wywołuje toString() w project, a nie w project.rootDir. Aby uzyskać wartość katalogu głównego, umieść wyrażenie ${project.rootDir} w nawiasach klamrowych:
```
myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
```
Więcej informacji znajdziesz w sekcji Szablony ciągów znaków w dokumentacji Kotlina.

Zmienianie rozszerzeń plików

Dołącz .kts do każdego pliku kompilacji podczas migracji jego zawartości. Na przykład wybierz plik kompilacji, taki jak settings.gradle. Zmień nazwę pliku na settings.gradle.kts i przekonwertuj jego zawartość na język Kotlin. Po migracji każdego pliku kompilacji sprawdź, czy projekt nadal się kompiluje.

Najpierw przenieś najmniejsze pliki, aby zdobyć doświadczenie, a potem przejdź do większych. W projekcie możesz mieć różne pliki kompilacji Kotlin i Groovy, więc nie musisz się spieszyć z wprowadzaniem zmian.

Zastąp `def` wartością `val` lub `var`

Zastąp def ciągiem val lub var, czyli sposobem definiowania zmiennych w Kotlinie. Oto deklaracja zmiennej w języku Groovy:

def building64Bit = false

Ten sam kod napisany w języku Kotlin:

val building64Bit = false

Właściwości logiczne poprzedź prefiksem `is`

Groovy używa logiki dedukcji właściwości na podstawie nazw właściwości. W przypadku właściwości logicznej foo jej metody dedukowane mogą mieć postać getFoo, setFoo lub isFoo. Dlatego po przekonwertowaniu na Kotlin musisz zmienić nazwy właściwości na metody dedukowane, które nie są obsługiwane przez Kotlin. Na przykład w przypadku elementów logicznych buildTypes DSL musisz dodać przed nimi prefiks is. Ten kod pokazuje, jak ustawić właściwości logiczne w Groovy:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

Poniżej znajdziesz ten sam kod w języku Kotlin. Pamiętaj, że właściwości są poprzedzone prefiksem is.

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

Konwertowanie list i map

Listy i mapy w językach Groovy i Kotlin są definiowane za pomocą innej składni. Groovy używa [], a Kotlin wywołuje metody tworzenia kolekcji bezpośrednio za pomocą listOf lub mapOf. Podczas migracji zastąp [] wartością listOf lub mapOf.

Oto jak zdefiniować listę w Groovy i Kotlin:

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

Ten sam kod napisany w języku Kotlin:

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

Oto jak zdefiniować mapę w Groovy i Kotlin:

def myMap = [key1: 'value1', key2: 'value2']

Ten sam kod napisany w języku Kotlin:

val myMap = mapOf("key1" to "value1", "key2" to "value2")

Konfigurowanie typów kompilacji

W języku DSL Kotlin domyślnie dostępne są tylko typy kompilacji debug i kompilacja do publikacji. Wszystkie inne niestandardowe typy kompilacji muszą być tworzone ręcznie.

W Groovy możesz używać typów kompilacji debug, release i niektórych innych bez konieczności ich wcześniejszego tworzenia. Poniższy fragment kodu pokazuje konfigurację z typami kompilacji debug, release i benchmark w Groovy.

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

Aby utworzyć równoważną konfigurację w Kotlin, musisz wyraźnie utworzyć typ kompilacji benchmark.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

Migracja z buildscript do bloku plugins

Jeśli kompilacja używa bloku buildscript {} do dodawania wtyczek do projektu, należy go refaktoryzować, aby używał bloku plugins {}. Blok plugins {} ułatwia stosowanie wtyczek i dobrze współpracuje z katalogami wersji.

Dodatkowo, gdy używasz bloku plugins {} w plikach kompilacji, Android Studio zna kontekst, nawet jeśli kompilacja się nie powiedzie. Ten kontekst pomaga wprowadzać poprawki w plikach DSL Kotlina, ponieważ umożliwia środowisku IDE Studio uzupełnianie kodu i podawanie innych przydatnych sugestii.

Znajdowanie identyfikatorów wtyczek

Blok buildscript {} dodaje wtyczki do ścieżki klasy kompilacji za pomocą współrzędnych Maven wtyczki, np. com.android.tools.build:gradle:7.4.0, natomiast blok plugins {} używa identyfikatorów wtyczek.

W przypadku większości wtyczek identyfikator wtyczki to ciąg znaków używany podczas ich stosowania za pomocą apply plugin. Na przykład te identyfikatory wtyczek są częścią wtyczki Androida do obsługi Gradle:

com.android.application
com.android.library
com.android.lint
com.android.test

Pełną listę wtyczek znajdziesz w repozytorium Maven Google.

Wtyczki Kotlin mogą być przywoływane przez wiele identyfikatorów wtyczek. Zalecamy używanie identyfikatora wtyczki w przestrzeni nazw i refaktoryzację ze skróconego identyfikatora w identyfikator wtyczki w przestrzeni nazw zgodnie z poniższą tabelą:

Skrócone identyfikatory wtyczek	Identyfikatory wtyczek z przestrzenią nazw
`kotlin`	`org.jetbrains.kotlin.jvm`
`kotlin-android`	`org.jetbrains.kotlin.android`
`kotlin-kapt`	`org.jetbrains.kotlin.kapt`
`kotlin-parcelize`	`org.jetbrains.kotlin.plugin.parcelize`

Wtyczki możesz też wyszukiwać w portalu wtyczek Gradle, centralnym repozytorium Maven i repozytorium Maven Google. Aby dowiedzieć się więcej o tym, jak działają identyfikatory wtyczek, przeczytaj artykuł Developing Custom Gradle Plugins (Tworzenie niestandardowych wtyczek Gradle).

Przeprowadzanie refaktoryzacji

Gdy poznasz identyfikatory używanych wtyczek, wykonaj te czynności:

Jeśli nadal masz repozytoria wtyczek zadeklarowane w bloku buildscript {}, przenieś je do pliku settings.gradle.
Dodaj wtyczki do bloku plugins {} w pliku build.gradle najwyższego poziomu. Musisz tutaj podać identyfikator i wersję wtyczki. Jeśli wtyczka nie musi być stosowana do projektu głównego, użyj apply false.
Usuń wpisy classpath z pliku build.gradle.kts najwyższego poziomu.
Zastosuj wtyczki, dodając je do bloku plugins {} w pliku build.gradle na poziomie modułu. Wystarczy, że podasz tutaj identyfikator wtyczki, ponieważ wersja jest dziedziczona z projektu głównego.
Usuń wywołanie apply plugin wtyczki z pliku build.gradle na poziomie modułu.

Na przykład ta konfiguracja używa bloku buildscript {}:

// Top-level build.gradle file
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
        ...
    }
}

// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")

Oto równoważna konfiguracja z użyciem bloku plugins {}:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.4.0' apply false
   id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   id 'org.jetbrains.kotlin.android'
   ...
}

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Konwertowanie bloku wtyczek

Stosowanie wtyczek z bloku plugins {} jest podobne w językach Groovy i Kotlin. Poniższy kod pokazuje, jak stosować wtyczki w Groovy, gdy używasz katalogów wersji:

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

Poniższy kod pokazuje, jak zrobić to samo w języku Kotlin:

// Top-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application) apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

Poniższy kod pokazuje, jak stosować wtyczki w Groovy, gdy nie używasz katalogów wersji:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

Poniższy kod pokazuje, jak zrobić to samo w języku Kotlin:

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version "7.3.0" apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

Więcej informacji o bloku plugins {} znajdziesz w sekcji Applying plugins (Stosowanie wtyczek) w dokumentacji Gradle.

Pozostałe postanowienia

Przykładowe kody w języku Kotlin dotyczące innych funkcji znajdziesz na tych stronach dokumentacji:

Jeśli masz konfigurację ProGuard, zapoznaj się z artykułem Włączanie zmniejszania, zaciemniania i optymalizacji.
Jeśli masz blok signingConfig {}, zapoznaj się z sekcją Usuwanie informacji o podpisywaniu z plików kompilacji.
Jeśli używasz właściwości w całym projekcie, zapoznaj się z artykułem Konfigurowanie właściwości w całym projekcie.

Znane problemy

Znany problem polega na tym, że szybkość kompilacji może być mniejsza w przypadku Kotlina niż Groovy.

Jak zgłaszać problemy

Instrukcje dotyczące podawania informacji, których potrzebujemy do rozwiązania problemu, znajdziesz w artykule Szczegóły dotyczące błędów narzędzi do kompilacji i Gradle. Następnie zgłoś błąd za pomocą publicznego narzędzia do rejestrowania błędów Google.

Więcej zasobów

Działający przykład plików kompilacji Gradle napisanych w Kotlinie znajdziesz w przykładowej aplikacji Now in Android na GitHubie.

Migracja konfiguracji kompilacji z Groovy do Kotlin Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Oś czasu

Typowe terminy

Nazwy plików skryptów

Konwertowanie składni

Dodaj nawiasy do wywołań metod

Dodaj = do rozmów dotyczących projektu

Konwertowanie ciągów znaków

Zmienianie rozszerzeń plików

Zastąp def wartością val lub var

Właściwości logiczne poprzedź prefiksem is

Konwertowanie list i map

Konfigurowanie typów kompilacji

Migracja z buildscript do bloku plugins

Znajdowanie identyfikatorów wtyczek

Przeprowadzanie refaktoryzacji

Konwertowanie bloku wtyczek

Pozostałe postanowienia

Znane problemy

Jak zgłaszać problemy

Więcej zasobów

Migracja konfiguracji kompilacji z Groovy do Kotlin

Dodaj `=` do rozmów dotyczących projektu

Zastąp `def` wartością `val` lub `var`

Właściwości logiczne poprzedź prefiksem `is`