0Pricing
Kotlin Academy · Lekcja

Integracja procesorów KSP z kompilacją Gradle

Skonfiguruj KSP w Gradle, dodaj wygenerowane źródła i debuguj dane wyjściowe procesora.

Integracja procesorów KSP z kompilacją Gradle to bezpłatna lekcja Kotlin Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Kotlin Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Struktura wielomodułowa

Typowa konfiguracja KSP obejmuje co najmniej dwa moduły: :annotation (zawiera klasy adnotacji) oraz :processor (zawiera SymbolProcessor). Moduł korzystający stosuje wtyczkę KSP i deklaruje zależności ksp oraz implementation.

Stosowanie wtyczki KSP

W pliku build.gradle.kts modułu korzystającego:

plugins {
    kotlin("jvm")  // or android, multiplatform
    id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}

Deklarowanie zależności ksp

Należy użyć konfiguracji ksp (a nie implementation), aby dodać procesor KSP. Procesor jest uruchamiany wyłącznie podczas kompilacji i nie jest dołączany do artefaktu końcowego:

dependencies {
    implementation(project(":annotation"))
    ksp(project(":processor"))
}

Katalogi wygenerowanego kodu źródłowego

KSP zapisuje wygenerowane pliki w katalogu build/generated/ksp/<sourceSet>/kotlin/. Wtyczka KSP automatycznie dodaje te katalogi do zestawu źródeł Kotlin, dzięki czemu wygenerowane klasy są widoczne w kodzie bez ręcznej konfiguracji.

Przekazywanie opcji do procesora

Opcje przekazywane podczas kompilacji z Gradle do procesora należy określać za pomocą ksp { arg("key", "value") }. Odczytuje się je w procesorze za pomocą environment.options["key"]:

// build.gradle.kts (consumer)
ksp {
    arg("generateMocks", "true")
    arg("outputPackage", "com.example.generated")
}

Odczytywanie opcji w procesorze

W metodzie SymbolProcessorProvider.create() opcje można pobrać ze środowiska:

class MyProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
        val genMocks = environment.options["generateMocks"] == "true"
        return MyProcessor(environment.codeGenerator, environment.logger, genMocks)
    }
}

Kompilacje przyrostowe

KSP śledzi zależności między danymi wejściowymi a wynikowymi. Podczas wywoływania codeGenerator.createNewFile() należy powiązać każdy wygenerowany plik z jego symbolami źródłowymi. KSP pomija wtedy ponowne przetwarzanie, jeśli żadne ze śledzonych danych wejściowych się nie zmieniły.

val deps = Dependencies(aggregating = false, *symbols.map { it.containingFile!! }.toTypedArray())
codeGenerator.createNewFile(deps, packageName, fileName)

KSP z Androidem

W projektach Android należy zastąpić kapt przez ksp zarówno w deklaracji wtyczki, jak i zależności. Jeśli zachowanie procesora ma się różnić między typami kompilacji, należy użyć konfiguracji zależnych od wariantu, takich jak kspDebug lub kspRelease.

KSP z Kotlin Multiplatform

W projekcie KMP należy zastosować wtyczkę KSP i użyć add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor")) albo skróconych konfiguracji, takich jak kspCommonMainMetadata, kspJvmMain itd., zależnie od obsługiwanych przez procesor platform docelowych.

Wyświetlanie wygenerowanych plików

Po uruchomieniu ./gradlew build (lub kspKotlin / kspDebugKotlin w przypadku Androida) należy przejrzeć katalog build/generated/ksp/. IntelliJ i Android Studio oznaczają te foldery jako wygenerowane źródła i umożliwiają przejście z miejsc użycia do wygenerowanych deklaracji.

Debugowanie procesora

Zadanie Gradle należy uruchomić z opcją --debug albo dodać jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") do konfiguracji ksp, aby podłączyć zdalny debuger do JVM przetwarzania adnotacji.

Szybkie sprawdzenie

Jakiej konfiguracji Gradle używa się do dodania procesora KSP, który jest uruchamiany podczas kompilacji, ale nie jest dołączany do ścieżki klas środowiska uruchomieniowego?

Podsumowanie: Integracja KSP z kompilacją Gradle

Najważniejsze informacje:

  • Należy zastosować wtyczkę com.google.devtools.ksp i dodać procesor jako zależność ksp()
  • Wygenerowane źródła trafiają do katalogu build/generated/ksp/ i są automatycznie dodawane do zestawu źródeł
  • Opcje należy przekazywać z Gradle za pomocą ksp { arg() }, a odczytywać za pomocą environment.options
  • Do poprawnego wykonywania kompilacji przyrostowych należy używać Dependencies razem z createNewFile()
  • Rozwiązanie działa z Androidem (konfiguracje wariantów) i Kotlin Multiplatform

Często zadawane pytania

Czy lekcja „Integracja procesorów KSP z kompilacją Gradle” jest bezpłatna?

Tak — pełny tekst „Integracja procesorów KSP z kompilacją Gradle” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Kotlin Academy, przejdź na CoddyKit PRO. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Integracja procesorów KSP z kompilacją Gradle”?

Skonfiguruj KSP w Gradle, dodaj wygenerowane źródła i debuguj dane wyjściowe procesora. Ćwiczysz Kotlin Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Kotlin Academy?

Nie wymagamy żadnego doświadczenia. Kotlin Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Integracja procesorów KSP z kompilacją Gradle”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Kotlin Academy?

Tak. Każda lekcja Kotlin Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. KSP a KAPT: dlaczego KSP jest szybsze
  2. Pisanie pierwszego SymbolProcessor
  3. Generowanie plików źródłowych Kotlina za pomocą KotlinPoet
  4. Integracja procesorów KSP z kompilacją Gradle
← Powrót do Kotlin Academy