0Pricing
Kotlin Academy · Aula

Integrando processadores KSP a uma compilação Gradle

Configure KSP no Gradle, adicione fontes geradas e depure a saída do processador.

Integrando processadores KSP a uma compilação Gradle é uma aula grátis de Kotlin Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Kotlin Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Kotlin Academy inclui 4 aulas no total.

Estrutura com vários módulos

Uma configuração típica do KSP tem pelo menos dois módulos: :annotation (contém suas classes de anotação) e :processor (contém o SymbolProcessor). O módulo consumidor aplica o plug-in KSP e declara dependências ksp e implementation.

Aplicando o plug-in KSP

No build.gradle.kts do módulo consumidor:

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

Declarando a dependência ksp

Use a configuração ksp (não implementation) para adicionar um processador KSP. O processador é executado apenas durante a compilação e não é incluído no artefato final:

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

Diretórios do código-fonte gerado

O KSP grava os arquivos gerados em build/generated/ksp/<sourceSet>/kotlin/. O plug-in KSP adiciona automaticamente esses diretórios ao conjunto de código-fonte Kotlin, portanto as classes geradas ficam visíveis para o seu código sem configuração manual.

Passando opções ao processador

Passe opções de compilação do Gradle para o seu processador por meio de ksp { arg("key", "value") }. Leia-as no processador usando environment.options["key"]:

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

Lendo opções no processador

No método SymbolProcessorProvider.create(), acesse as opções a partir do ambiente:

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

Compilações incrementais

O KSP acompanha as dependências entre entradas e saídas. Associe cada arquivo gerado aos símbolos de origem ao chamar codeGenerator.createNewFile(). Assim, o KSP ignora o reprocessamento quando nenhuma das entradas acompanhadas é alterada.

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

KSP com Android

Em projetos Android, substitua kapt por ksp tanto nas declarações do plug-in quanto nas declarações de dependências. Use configurações específicas para cada variante, como kspDebug ou kspRelease, se precisar que o comportamento do processador seja diferente entre os tipos de compilação.

KSP com Kotlin Multiplatform

Em um projeto KMP, aplique o plug-in KSP e use add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor")) ou a forma abreviada kspCommonMainMetadata, kspJvmMain etc., dependendo dos destinos compatíveis com o seu processador.

Visualizando arquivos gerados

Depois de executar ./gradlew build (ou kspKotlin / kspDebugKotlin para Android), examine build/generated/ksp/. O IntelliJ e o Android Studio marcam essas pastas como código-fonte gerado e permitem navegar dos usos até as declarações geradas.

Depurando um processador

Execute a tarefa do Gradle com --debug ou adicione jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") à configuração ksp para conectar um depurador remoto à JVM de processamento de anotações.

Verificação rápida

Qual configuração do Gradle é usada para adicionar um processador KSP que é executado durante a compilação, mas não é incluído no caminho de classes de execução?

Recapitulação: integrando o KSP a uma compilação do Gradle

Principais conclusões:

  • Aplique o plug-in com.google.devtools.ksp; adicione o processador com a dependência ksp()
  • O código-fonte gerado fica em build/generated/ksp/ e é adicionado automaticamente ao conjunto de código-fonte
  • Passe opções do Gradle usando ksp { arg() }; leia-as por meio de environment.options
  • Use Dependencies com createNewFile() para recompilações incrementais precisas
  • Funciona com Android (configurações por variante) e Kotlin Multiplatform

Perguntas Frequentes

A aula “Integrando processadores KSP a uma compilação Gradle” é grátis?

Sim — o texto completo de “Integrando processadores KSP a uma compilação Gradle” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Kotlin Academy, atualize para CoddyKit PRO. O curso de Kotlin Academy inclui 4 aulas no total.

O que vou aprender em “Integrando processadores KSP a uma compilação Gradle”?

Configure KSP no Gradle, adicione fontes geradas e depure a saída do processador. Você pratica Kotlin Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Kotlin Academy?

Nenhuma experiência prévia é necessária. Kotlin Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Integrando processadores KSP a uma compilação Gradle”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Kotlin Academy?

Sim. Cada aula de Kotlin Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. KSP vs KAPT: por que KSP é mais rápido
  2. Escrevendo seu primeiro SymbolProcessor
  3. Gerando arquivos de código-fonte Kotlin com KotlinPoet
  4. Integrando processadores KSP a uma compilação Gradle
← Voltar para Kotlin Academy