Migracja z Kapt do KSP

Kapt (narzędzie do przetwarzania adnotacji w Kotlinie) umożliwia korzystanie z procesorów adnotacji w języku Java w przypadku kodu Kotlin, nawet jeśli nie obsługują one Kotlina. Polega to na wygenerowaniu z plików Kotlina zaczepów Javy, które mogą odczytać procesory. Generowanie zaczepów to kosztowna operacja, która ma znaczący wpływ na szybkość kompilacji.

KSP (Kotlin Symbol Processing) to alternatywa dla kapt, która obsługuje Kotlina. KSP analizuje kod Kotlina bezpośrednio, co jest do 2 razy szybsze. Lepiej też rozumie konstrukcje języka Kotlin.

Podczas migracji możesz uruchamiać kapt i KSP w tym samym projekcie. Migrację możesz przeprowadzić moduł po module i bibliotekę po bibliotece.

Oto przegląd kroków migracji:

  1. Sprawdź biblioteki, których używasz do obsługi KSP
  2. Dodawanie wtyczki KSP do projektu
  3. Zastępowanie procesorów adnotacji za pomocą KSP
  4. Usuń wtyczkę kapt

Sprawdź biblioteki, których używasz do obsługi KSP

Na początek sprawdź, czy biblioteki, których używasz z kapt, obsługują już KSP. Dotyczy to wielu popularnych bibliotek (w tym Dagger, Glide, Room i Moshi), a inne biblioteki również dodają obsługę.

Listę obsługiwanych bibliotek znajdziesz w dokumentacji lub w dokumentacji i systemie śledzenia błędów bibliotek, których używasz.

Dodawanie wtyczki KSP do projektu

Najpierw zadeklaruj wtyczkę KSP w pliku build.gradle.kts najwyższego poziomu. Pamiętaj, aby wybrać wersję KSP zgodną z wersją Kotlina w Twoim projekcie. Listę wersji znajdziesz na stronie GitHub KSP.

Kotlin

plugins {
    id("com.google.devtools.ksp") version "2.0.21-1.0.27" apply false
}

Groovy

plugins {
    id 'com.google.devtools.ksp' version '2.0.21-1.0.27' apply false
}

Następnie włącz KSP w pliku build.gradle.kts na poziomie modułu:

Kotlin

plugins {
    id("com.google.devtools.ksp")
}

Groovy

plugins {
    id 'com.google.devtools.ksp'
}

Zastępowanie procesorów adnotacji za pomocą KSP

Po włączeniu KSP możesz zacząć zastępować kapt przez KSP. W przypadku większości bibliotek wystarczy w deklaracji zależności zastąpić kapt przez ksp, ponieważ procesor adnotacji i procesor KSP są dostarczane w tym samym pliku.

Kotlin

dependencies {
    kapt("androidx.room:room-compiler:2.5.0")
    ksp("androidx.room:room-compiler:2.5.0")
}

Groovy

dependencies {
    kapt 'androidx.room:room-compiler:2.5.0'
    ksp 'androidx.room:room-compiler:2.5.0'
}

Po przejściu na KSP zsynchronizuj i skompiluj projekt, aby sprawdzić, czy nadal działa prawidłowo.

Oto kilka typowych problemów:

  • Niektóre biblioteki nie obsługują dokładnie tego samego zestawu funkcji w przypadku kapt i KSP. Jeśli po migracji kod przestanie działać, sprawdź dokumentację biblioteki.
  • KSP zawiera dokładniejsze informacje o typach Kotlina niż kapt (np. o możliwości braku wartości), co oznacza, że procesory KSP mogą dokładniej sprawdzać wymagania dotyczące typów. Może to wymagać wprowadzenia poprawek w kodzie źródłowym, a także zaktualizowania plików kompilacji.
  • Jeśli wcześniej przekazywałeś argumenty do procesora adnotacji, teraz musisz je przekazać do KSP. Pamiętaj, że format argumentów może się różnić w przypadku kapt i KSP. Aby dowiedzieć się więcej, zapoznaj się z dokumentacją KSP i dokumentacją używanej biblioteki.

Usuń wtyczkę kapt

Jeśli w module nie ma już zależności związanych z kapt, usuń wtyczkę kapt.

Jeśli została zadeklarowana w bloku wtyczek:

Kotlin

plugins {
    id("org.jetbrains.kotlin.kapt")
}

Groovy

plugins {
    id 'org.jetbrains.kotlin.kapt'
}

Jeśli używasz składni wtyczki za pomocą Groovy:

apply plugin: 'kotlin-kapt'

Musisz też usunąć pozostałe konfiguracje związane z kapt, takie jak:

Kotlin


kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy


kapt {
    correctErrorTypes true
    useBuildCache true
}

Dodatkowe materiały