Migracja konfiguracji kompilacji z Groovy do Kotlin

Wtyczka Androida do obsługi Gradle w wersji 4.0 obsługuje teraz używanie Kotlina w kompilacji Gradle jako zamiennik Groovy, języka programowania, jest tradycyjnie używany w plikach konfiguracji Gradle.

Do pisania skryptów Gradle wolimy Kotlina niż Groovy, ponieważ jest bardziej czytelny i oferuje lepsze sprawdzanie w czasie kompilowania oraz obsługę IDE.

Choć Kotlin oferuje obecnie lepszą integrację z kodem Android Studio, w edytorze Groovy, kompilacje korzystające z Kotlina są zwykle wolniejsze niż korzysta z Groovy, więc podejmując decyzję o zakupie, migracji danych.

Ta strona zawiera podstawowe informacje o konwertowaniu Gradle kompiluje pliki, w tym Groovy i Kotlin. Bardziej kompleksowa migracja zapoznaj się z oficjalną dokumentację.

Oś czasu

Uwaga: domyślnym językiem konfiguracji kompilacji jest Kotlin, począwszy od Żyrafa z Androidem Studio Jeśli używasz AGP 8.1 i DSL Kotlin należy używać wersji Gradle 8.1, aby uzyskać najlepsze rezultaty.

Począwszy od Android Studio Giraffe, nowe projekty będą korzystać z DSLL Kotlin (build.gradle.kts) domyślnie na potrzeby konfiguracji kompilacji. Dzięki temu niż Groovy DSL (build.gradle) ze składnią podświetlania, uzupełniania kodu i przechodzenia do deklaracji. Aby dowiedzieć się więcej, zobacz Gradle Kotlin DSL Primer

Często używane terminy

Kotlin DSL: odnosi się głównie do wtyczki Androida do obsługi Gradle: Kotlin DSL. lub, czasami, który jest podstawą Gradle Kotlin DSL.

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

Nazewnictwo plików skryptu

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

• Pliki kompilacji Gradle napisane w Groovy mają rozszerzenie nazwy pliku .gradle.
• Pliki kompilacji Gradle napisane w Kotlin korzystają z nazwy pliku .gradle.kts .

Konwertuj składnię

Istnieje kilka ogólnych różnic w składni między Groovy a Kotlinem, więc musisz zastosować te zmiany w swoich skryptach kompilacji.

Dodawanie nawiasów do wywołań metod

Wskazówka: w pierwszym kroku, nawet przed zmianą rozszerzeń pliku, dodaj nawiasy do swojego Groovy Code. To ułatwia konwersję na Kotlin.

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

compileSdkVersion 30

Ten sam kod jest zapisany w kotlinie:

compileSdkVersion(30)

Dodaj użytkownika = do połączeń w ramach przypisania

Wskazówka: zanim zmienisz rozszerzenia pliku, dodaj = do kodu Groovy. To ułatwia konwersję na Kotlin.

Groovy DSL pozwala pominąć operator przypisania =, gdy przypisywanie właściwości, natomiast Kotlin tego wymaga. Ten kod pokazuje, jak przypisz 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 Kotlin:

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

Konwertuj ciągi znaków

Groovy i Kotlin mają te różnice:

• Podwójny cudzysłów dla ciągów znaków: Choć Groovy pozwala na definiowanie ciągów znaków za pomocą pojedynczych cudzysłowów, Kotlin wymaga podwójny cudzysłów.

• Interpolacja ciągów znaków w wyrażeniach z kropkami: w Groovy możesz używać: tylko prefiks $ dla interpolacje ciągów znaków na wyrażeniach z kropkami, ale Kotlin wymaga, by były one otoczone nawiasami klamrowymi. Na przykład w aplikacji Groovy możesz użyć $project.rootDir jak w tym fragmencie:

      myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
      

  W Kotlin jednak poprzedni kod wywołuje metodę toString() project, nie w aplikacji project.rootDir. Aby uzyskać wartość katalogu głównego, umieść wyrażenie ${project.rootDir} nawiasami klamrowymi:

      myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
      

  Więcej informacji: Szablony ciągów tekstowych w dokumentacji Kotlin.

Zmiana rozszerzeń plików

Dołącz .kts do każdego pliku kompilacji podczas przenoszenia jego zawartości. Przykład: wybierz plik kompilacji, np. settings.gradle. Zmień nazwę pliku na settings.gradle.kts i przekonwertuj zawartość pliku na Kotlin. Upewnij się, że atrybuty projekt nadal kompiluje się po migracji każdego pliku kompilacji.

Zacznij od migracji najmniejszych plików, zyskaj doświadczenie i dopiero potem kontynuuj. Dostępne opcje mamy w projekcie mieszankę plików kompilacji Kotlin i Groovy, więc poświęćcie czas i starannie wykonać ruch.

Zamień def na val lub var

Zastąp def elementem val lub var, który jest sposobu definiowania zmiennych w kotlinie. To jest deklaracja zmiennej w Groovy:

def building64Bit = false

Ten sam kod jest zapisany w kotlinie:

val building64Bit = false

Właściwości logiczne prefiksu z is

Świetny sposób korzysta z metod odliczenia za usługi na podstawie nazw właściwości. W przypadku właściwości logicznej foo są to metody dedukcji to getFoo, setFoo lub isFoo. Tak więc po przekonwertowaniu na Kotlin musisz zmienić nazwy właściwości na metody dedukcji które nie są obsługiwane przez Kotlin. Na przykład w przypadku funkcji buildTypes elementu logicznego DSL, poprzedź je prefiksem 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 znajduje się ten sam kod w Kotlin. Pamiętaj, że właściwości są poprzedzone prefiksem do is.

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

Konwertuj listy i mapy

Listy i mapy w Groovy i Kotlin są zdefiniowane przy użyciu innej składni. Odlotowe korzysta z metody [], a Kotlin wywołuje metody tworzenia kolekcji bezpośrednio za pomocą listOf lub mapOf. Pamiętaj, aby zastąpić [] elementem listOf lub mapOf, gdy migracji.

Aby zdefiniować listę w trybie Groovy i Kotlin:

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

Ten sam kod jest zapisany w kotlinie:

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

Oto jak zdefiniować mapę w grze Groovy vs Kotlin:

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

Ten sam kod jest zapisany w kotlinie:

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

Skonfiguruj typy kompilacji

W DSL Kotlin dostępne są tylko typy kompilacji do debugowania i kompilacji wprost. Pozostałe niestandardowe typy kompilacji należy tworzyć ręcznie.

W Groovy możesz używać debugowania, wersji i niektórych innych typów kompilacji bez w pierwszej kolejności. Poniższy fragment kodu zawiera konfigurację z parametrem debug, release i Kompilacja benchmark typy w Groovy.

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

Aby utworzyć równoważną konfigurację w Kotlin, musisz bezpośrednio utworzyć Typ kompilacji: benchmark.

buildTypes {
 debug {
   ...
 }

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

Przejście z kompilacji na blok wtyczek

Jeśli Twoja kompilacja używa parametru buildscript {} aby dodać wtyczki do projektu, musisz dokonać refaktoryzacji, aby używać plugins {} zablokować. Blok plugins {} ułatwia stosowanie wtyczek i ułatwia stosowanie wtyczek dobrze działa katalogi wersji.

Ponadto, jeśli w plikach kompilacji użyjesz bloku plugins {}, Android Studio zna kontekst nawet w przypadku niepowodzenia kompilacji. Ten kontekst pomaga wprowadzać poprawki w plikach DSL Kotlin, ponieważ umożliwia IDE Studio uzupełniać kod i przekazywać inne pomocne sugestie.

Znajdowanie identyfikatorów wtyczek

Blok buildscript {} dodaje wtyczki do ścieżki klasy kompilacji za pomocą polecenia Współrzędne Maven wtyczki, na przykład com.android.tools.build:gradle:7.4.0, blok plugins {} korzysta z identyfikatorów wtyczek.

W przypadku większości wtyczek identyfikator to ciąg znaków używany przy stosowaniu apply plugin Na przykład poniższe identyfikatory wtyczek są częścią Wtyczka Androida do obsługi Gradle:

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

Pełną listę wtyczek znajdziesz na stronie Repozytorium Google Maven.

Do wtyczek Kotlin może odwoływać się wiele identyfikatorów wtyczek. Zalecamy użycie metody i refaktoryzacji ze skróconego identyfikatora wtyczki z przestrzenią nazw na identyfikator wtyczki ta tabela:

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ż wyszukać na Portal wtyczek Gradle, Centralne repozytorium Maven oraz repozytorium Google Maven, Odczytano Tworzenie niestandardowych wtyczek Gradle .

Przeprowadź refaktoryzację.

Po zapoznaniu się z identyfikatorami używanych wtyczek wykonaj te czynności:

1. Jeśli nadal masz repozytoria dla wtyczek zadeklarowanych w buildscript {} , przenieś je do settings.gradle .

2. Dodaj wtyczki do bloku plugins {} na najwyższym poziomie. build.gradle. Musisz podać identyfikator oraz z wersją wtyczki. Jeśli wtyczka nie musi zostanie zastosowany 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 build.gradle na poziomie modułu. Musisz tylko określić parametr Identyfikator, ponieważ wersja jest dziedziczona z projektu głównego.

5. Usuń wywołanie wtyczki apply plugin na poziomie modułu build.gradle.

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")

Jest to równoważna konfiguracja z wykorzystaniem 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 Groovy i Kotlin. Ten kod pokazuje, jak stosować wtyczki w Groovy, gdy używasz katalogi 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 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)
   ...
}

Ten kod pokazuje, jak używać wtyczek w Groovy, gdy nie przy użyciu 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 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 Stosowanie wtyczki w dokumentacji Gradle.

Różne

Przykładowe fragmenty kodu Kotlin z innymi funkcjami znajdziesz w tym artykule: strony dokumentacji:

• Jeśli masz konfigurację ProGuard, zapoznaj się z artykułem Włącz zmniejszanie, zaciemnianie i optymalizację.
• Jeśli masz blokadę typu signingConfig {}, zapoznaj się z sekcją Usuwanie danych podpisywania z plików kompilacji.
• Jeśli używasz usług na poziomie projektu, zapoznaj się z artykułem Konfigurowanie usług na poziomie projektu usługi.

.

Uwaga: chociaż Gradle pozwala definiować w module właściwości dla całego projektu należy unikać ich stosowania, ponieważ moduły mają te same właściwości, do połączenia. Łączenie modułów utrudnia późniejsze wyeksportowanie modułu. jako samodzielny projekt i uniemożliwia Gradle użycie projektu równoległego. aby przyspieszyć kompilacje obejmujące wiele modułów.

Znane problemy

Obecnie występuje znany problem. że w Kotlin szybkość kompilacji może być wolniejsza niż w Groovy.

Jak zgłaszać problemy

Aby dowiedzieć się, jak podać informacje potrzebne do oceny problemu, zobacz Szczegóły narzędzi do kompilacji i błędów Gradle. Następnie: zgłoś błąd na stronie publicznego narzędzia do rejestrowania problemów.

Więcej materiałów

Praktyczny przykład plików kompilacji Gradle zapisanych w kotlinie znajdziesz Przykładowa aplikacja Now w Androidzie w GitHubie.