Migracja z Kapt do KSP

Kapt (narzędzie do przetwarzania adnotacji w języku Kotlin) umożliwia używanie procesorów adnotacji Javy z kodem w języku Kotlin, nawet jeśli te procesory nie obsługują języka Kotlin. W tym celu generuje z plików Kotlin klasy pośredniczące Javy, które mogą być odczytywane przez procesory. Generowanie tych klas zastępczych jest kosztowną operacją i ma znaczny wpływ na szybkość kompilacji.

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

Podczas migracji możesz uruchamiać kapt i KSP obok siebie w projekcie, a migrację możesz przeprowadzać moduł po module, biblioteka po bibliotece.

Oto ogólny opis czynności związanych z migracją:

  1. Sprawdzanie bibliotek pod kątem obsługi KSP
  2. Dodawanie wtyczki KSP do projektu
  3. Zastępowanie procesorów adnotacji procesorami KSP
  4. Usuwanie wtyczki kapt

Sprawdzanie bibliotek pod kątem 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 dodają obsługę.

Listę obsługiwanych bibliotek znajdziesz w dokumentacji. Możesz też zapoznać się z dokumentacją i narzędziem Issue Tracker 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
}

Dynamiczny

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

Dynamiczny

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

Zastępowanie procesorów adnotacji procesorami KSP

Po włączeniu KSP możesz zacząć zastępować użycie kapt przez KSP. W przypadku większości bibliotek wymaga to tylko zmiany 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")
}

Dynamiczny

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

Usuwanie wtyczki kapt

Gdy w module nie ma już żadnych 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")
}

Dynamiczny

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

Jeśli używasz składni apply plugin 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
}

Dynamiczny


kapt {
    correctErrorTypes true
    useBuildCache true
}

Dodatkowe materiały