Migracja konfiguracji kompilacji z Groovy do Kotlin

Wtyczka Androida do obsługi Gradle w wersji 4.0 wprowadziła obsługę języka Kotlin w konfiguracji kompilacji Gradle jako zamiennika języka Groovy, który był tradycyjnie używany w plikach konfiguracyjnych Gradle.

Kotlin jest preferowany od Groovy do pisania skryptów Gradle, ponieważ jest bardziej czytelny i oferuje lepsze sprawdzanie w czasie kompilacji oraz obsługę IDE.

Chociaż Kotlin oferuje obecnie lepszą integrację w edytorze kodu Android Studio w porównaniu z Groovy, kompilacje z użyciem Kotlina są zwykle wolniejsze niż kompilacje z użyciem 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 Kotlin. Bardziej szczegółowy przewodnik po migracji znajdziesz w oficjalnej dokumentacji Gradle.

Oś czasu

Uwaga: od wersji Androida Studio Giraffe Kotlin jest domyślnym językiem konfiguracji kompilacji. Jeśli używasz AGP 8.1 i Kotlin DSL do konfigurowania kompilacji, dla najlepszego działania zalecamy używanie Gradle 8.1.

Od Androida Studio Giraffe nowe projekty domyślnie używają Kotlin DSL (build.gradle.kts) do konfiguracji kompilacji. 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 języku Kotlin DSL w Gradle.

Często używane terminy

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

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

Nazewnictwo plików skryptów

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

• Pliki kompilacji Gradle napisane w Groovy używają rozszerzenia nazwy pliku .gradle.
• Pliki kompilacji Gradle napisane w Kotlinie mają rozszerzenie .gradle.kts.

Konwertowanie składni

Między Groovy a Kotlinem występują pewne ogólne różnice w składni, dlatego musisz wprowadzić te zmiany w całym skrypcie kompilacji.

Dodawanie nawiasów do wywołań metod

Wskazówka: na początek, jeszcze przed zmianą rozszerzeń plików, dodaj nawiasy do kodu Groovy. Ułatwia to konwersję na język Kotlin.

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

compileSdkVersion 30

Ten sam kod w języku Kotlin:

compileSdkVersion(30)

Dodawanie symbolu = do połączeń dotyczących projektów

Wskazówka: przed zmianą rozszerzeń plików dodaj do kodu Groovy znak =. Ułatwia to konwersję na język Kotlin.

W przypadku przypisywania właściwości język Groovy DSL umożliwia pominięcie operatora przypisania =, natomiast Kotlin wymaga jego użycia. Ten kod pokazuje, jak przypisywać właściwości w Groovy:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

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

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

Konwertowanie ciągów

Oto różnice w ciągach znaków między Groovy a Kotlinem:

• Podwójne cudzysłowy w przypadku ciągów: Groovy umożliwia definiowanie ciągó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 kropką: w Groovy możesz używać tylko prefiksu $ w przypadku interpolacji ciągów znaków w wyrażeniach z kropką, ale Kotlin wymaga, aby wyrażenia z kropką były umieszczane w nawiasach klamrowych. 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"
      

  W Kotlinie jednak powyższy kod wywołuje funkcję toString() na obiekcie project, a nie na obiekcie 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 dokumentacji języka Kotlin w artykule String templates (w języku angielskim).

Zmienianie rozszerzeń plików

Podczas przenoszenia zawartości każdego pliku kompilacji dodaj do niego znak .kts. Na przykład wybierz plik kompilacji, taki jak plik 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, zdobądź doświadczenie, a potem przejdź dalej. W projekcie możesz mieć pliki kompilacji w językach Kotlin i Groovy, więc poświęć trochę czasu na dokładne przeprowadzenie tej zmiany.

Zastąp def elementem val lub var

Zastąp def wartością val lub var, czyli sposobem definiowania zmiennych w Kotlinie. Oto deklaracja zmiennej w Groovy:

def building64Bit = false

Ten sam kod w języku Kotlin:

val building64Bit = false

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

Groovy używa logiki wnioskowania o właściwościach na podstawie nazw właściwości. W przypadku właściwości logicznej foo jej wywnioskowane metody mogą mieć postać getFoo, setFoo lub isFoo. Dlatego po przekonwertowaniu na język Kotlin musisz zmienić nazwy właściwości na wywnioskowane metody, które nie są obsługiwane przez ten język. Na przykład w przypadku elementów logicznych DSL musisz dodać przed nimi prefiks is.buildTypes 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 mają prefiks 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 w sposób jawny, używając listOf lub mapOf. Podczas migracji zastąp [] wartością listOf lub mapOf.

Oto jak zdefiniować listę w Groovy i Kotlinie:

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

Ten sam kod w języku Kotlin:

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

Oto jak zdefiniować mapę w Groovy i Kotlinie:

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

Ten sam kod w języku Kotlin:

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

Konfigurowanie typów kompilacji

W Kotlin DSL tylko typy kompilacji debug i release są dostępne niejawnie. 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 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ć odpowiednią konfigurację w języku Kotlin, musisz jawnie utworzyć typ kompilacji benchmark.

buildTypes {
 debug {
   ...
 }

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

Migracja ze skryptu kompilacji do bloku wtyczek

Jeśli kompilacja używa bloku buildscript {} do dodawania wtyczek do projektu, zmień ją tak, aby zamiast tego używała bloku plugins {}. Blok plugins {} ułatwia stosowanie wtyczek i dobrze współpracuje z katalogami wersji.

Dodatkowo, gdy w plikach kompilacji używasz bloku plugins {}, Android Studio zna kontekst nawet wtedy, gdy kompilacja się nie powiedzie. Ten kontekst ułatwia wprowadzanie poprawek w plikach Kotlin DSL, ponieważ umożliwia środowisku IDE Studio uzupełnianie kodu i wyświetlanie innych przydatnych sugestii.

Znajdowanie identyfikatorów wtyczek

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

W przypadku większości wtyczek identyfikator wtyczki to ciąg znaków używany podczas stosowania wtyczek za pomocą funkcji 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 Google Maven.

Wtyczki Kotlin mogą być przywoływane przez wiele identyfikatorów wtyczek. Zalecamy używanie identyfikatora wtyczki z przestrzenią nazw i przeprowadzenie refaktoryzacji z identyfikatora skróconego na identyfikator wtyczki z przestrzenią nazw zgodnie z tą tabelą:

Identyfikatory wtyczek w skróconej formie	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

Wtyczek możesz też szukać w portalu wtyczek Gradle, centralnym repozytorium Maven i repozytorium Google Maven. Przeczytaj artykuł Developing Custom Gradle Plugins (Tworzenie niestandardowych wtyczek Gradle), aby dowiedzieć się więcej o działaniu identyfikatorów wtyczek.

Przeprowadź refaktoryzację

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

1. Jeśli nadal masz repozytoria wtyczek zadeklarowane w bloku buildscript {}, przenieś je do pliku settings.gradle.

2. Dodaj wtyczki do bloku plugins {} w pliku najwyższego poziomu build.gradle. Musisz tu podać identyfikator i wersję wtyczki. Jeśli wtyczka nie musi być stosowana do projektu głównego, użyj apply false.

3. Usuń wpisy classpath z pliku build.gradle.kts najwyższego poziomu.

4. Zastosuj wtyczki, dodając je do bloku plugins {} w pliku build.gradle na poziomie modułu. W tym miejscu musisz podać tylko identyfikator wtyczki, ponieważ wersja jest dziedziczona z projektu głównego.

5. Usuń wywołanie wtyczki apply plugin 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 przypadku języków Groovy i Kotlin. Poniższy kod pokazuje, jak zastosować 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 to samo zrobić w Kotlinie:

// 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 zastosować 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 to samo zrobić w Kotlinie:

// 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 Stosowanie wtyczek w dokumentacji Gradle.

Różne

Przykłady kodu 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 signingConfig {} blok, zapoznaj się z artykułem Usuwanie informacji o podpisywaniu z plików kompilacji.
• Jeśli używasz właściwości obejmujących cały projekt, zapoznaj się z artykułem Konfigurowanie właściwości obejmujących cały projekt.

Ostrzeżenie: chociaż Gradle umożliwia definiowanie właściwości w całym projekcie na poziomie modułu, unikaj tego, ponieważ powoduje to powiązanie modułów, które współdzielą te właściwości. Sprzężenie modułów utrudnia późniejsze wyeksportowanie modułu jako samodzielnego projektu i uniemożliwia Gradle używanie równoległego wykonywania projektów w celu przyspieszenia kompilacji wielomodułowych.

Znane problemy

Obecnie znanym problemem jest to, że szybkość kompilacji może być mniejsza w przypadku języka Kotlin niż w przypadku języka Groovy.

Jak zgłaszać problemy

Instrukcje dotyczące podawania informacji potrzebnych do ustalenia priorytetu problemu znajdziesz w artykule Szczegóły dotyczące narzędzi do kompilacji i błędów Gradle. Następnie zgłoś błąd w publicznym narzędziu do rejestrowania błędów Google.

Więcej materiałów

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