Migracja z Kapt do KSP

Kapt (Kotlin Annotation Processing Tool) umożliwia używanie procesorów adnotacji Java z kodem Kotlin, nawet jeśli nie obsługują one tego języka. W tym celu generowane są z plików Kotlin stuby w języku Java, które mogą następnie odczytywać procesory. Generowanie tych elementów jest kosztowną operacją i ma znaczący wpływ na szybkość kompilacji.

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

Podczas migracji możesz w projekcie uruchamiać kapt i KSP jednocześnie. Migrację można przeprowadzać moduł po module i biblioteka po bibliotece.

Oto przegląd kroków migracji:

  1. Sprawdź, czy używane biblioteki obsługują KSP
  2. Dodawanie wtyczki KSP do projektu
  3. Zastępowanie procesorów adnotacji KSP
  4. Usuwanie wtyczki kapt

Sprawdź, czy używane biblioteki obsługują 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 dodają obsługę.

Listę obsługiwanych bibliotek znajdziesz w dokumentacji. Możesz też zapoznać się z dokumentacją i śledzić zgłoszenia dotyczące bibliotek, których używasz.

Dodawanie wtyczki KSP do projektu

Najpierw zadeklaruj wtyczkę KSP w pliku build.gradle.kts najwyższego poziomu. Listę wersji znajdziesz na stronie KSP w GitHubie.

Kotlin

plugins {
    id("com.google.devtools.ksp") version "2.3.4" apply false
}

Groovy

plugins {
    id 'com.google.devtools.ksp' version '2.3.4' 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 KSP

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

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, na które warto zwrócić uwagę:

  • 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ć, zapoznaj się z dokumentacją biblioteki.
  • KSP ma dokładniejsze informacje o typach w Kotlinie niż kapt (np. o możliwości przyjmowania wartości null), co oznacza, że procesory KSP mogą być bardziej precyzyjne w określaniu wymagań dotyczących typów. Oprócz aktualizacji plików kompilacji może to wymagać wprowadzenia poprawek w kodzie źródłowym.
  • Jeśli wcześniej przekazywano argumenty do procesora adnotacji, prawdopodobnie trzeba będzie teraz przekazywać je do KSP. Pamiętaj, że format argumentów może się różnić w zależności od kapt i KSP. Więcej informacji znajdziesz w dokumentacji KSP i dokumentacji używanej biblioteki.

Usuwanie wtyczki kapt

Gdy w module nie ma już zależności uwzględnionych w 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żywało składni wtyczki apply w Groovy:

apply plugin: 'kotlin-kapt'

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

Kotlin


kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy


kapt {
    correctErrorTypes true
    useBuildCache true
}

Dodatkowe materiały