Migracja z Kapt do KSP

Kapt (Kotlin Annotation Processing Tool) umożliwia stosowanie procesorów adnotacji Java z kodem Kotlin, nawet jeśli nie obsługują one konkretnej obsługi Kotlin. Jest to możliwe dzięki generowaniu z plików Kotlin fragmentów kodu Java, które mogą potem odczytać procesory. To wygenerowanie wycinka jest kosztowne i ma znaczny wpływ na szybkość kompilacji.

KSP (Kotlin Symbol Processing) to stworzona z góry Kotlin alternatywa dla kapt. KSP analizuje bezpośrednio kod Kotlin, co jest nawet 2 razy szybsze. Pozwala również lepiej zrozumieć konstrukcje językowe Kotlina.

Kapt jest obecnie w trybie konserwacji i w miarę możliwości zalecamy migrację z kapt do KSP. W większości przypadków ta migracja wymaga tylko wprowadzenia zmian w konfiguracji kompilacji projektu.

Podczas migracji możesz uruchamiać w projekcie kapt i KSP, a migracja może być realizowana moduł po bibliotece, z biblioteką.

Omówienie kroków migracji:

  1. Sprawdzanie bibliotek, których używasz do obsługi KSP
  2. Dodaj wtyczkę KSP do projektu
  3. Zastąp procesory adnotacji kluczem KSP
  4. Usuń wtyczkę kapt

Sprawdzanie bibliotek, których używasz do obsługi KSP

Zacznij od sprawdzenia, czy biblioteki, których używasz z użyciem narzędzia kapt, obsługują już KSP. Tak dzieje się w przypadku wielu popularnych bibliotek (np. Dagger, Glide, Room i Moshi), które również są obsługiwane.

Możesz sprawdzić listę obsługiwanych bibliotek w dokumentacji lub skorzystać z dokumentacji i narzędzia do śledzenia błędów, z których korzystasz.

Dodaj wtyczkę KSP do projektu

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

Kotlin

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

Odlotowy

plugins {
    id 'com.google.devtools.ksp' version '1.8.10-1.0.9' apply false
}

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

Kotlin

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

Odlotowy

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

Zastąp procesory adnotacji kluczem KSP

Po włączeniu KSP możesz zacząć zastępować przypadki użycia kapt KSP. W przypadku większości bibliotek wymaga to zmiany kapt na ksp w deklaracji zależności, ponieważ procesory adnotacji i KSP udostępniają ten sam artefakt.

Kotlin

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

Odlotowy

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

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

Oto kilka typowych problemów, na które należy uważać:

  • Niektóre biblioteki nie obsługują dokładnie tego samego zestawu funkcji z Kapt i KSP. Jeśli po migracji kod ulegnie awarii, sprawdź dokumentację biblioteki.
  • KSP ma dokładniejsze informacje o typie Kotlin niż kapt (np. dotyczące wartości null), co oznacza, że procesory KSP mogą dokładniej określać wymagania dotyczące typów. Może to też wymagać wprowadzenia poprawek w kodzie źródłowym oprócz aktualizacji plików kompilacji.
  • Jeśli wcześniej argumenty były przekazywane do procesora adnotacji, prawdopodobnie musisz je teraz przekazać do KSP. Pamiętaj, że w przypadku kapt i KSP format argumentów może być inny. Aby dowiedzieć się więcej, zapoznaj się z dokumentacją KSP i dokumentacją biblioteki, której używasz.

Usuń wtyczkę kapt

Gdy w module nie ma już zależności z elementem kapt, usuń wtyczkę kapt.

Jeśli zostało zadeklarowane w bloku wtyczek:

Kotlin

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

Odlotowy

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

Jeśli używany jest składnia wtyczki „Zastosuj” za pomocą Groovy:

apply plugin: 'kotlin-kapt'

Usuń też wszystkie pozostałe konfiguracje związane z kapt, takie jak:

Kotlin


kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Odlotowy


kapt {
    correctErrorTypes true
    useBuildCache true
}

Dodatkowe materiały