Migrar do kapt para o KSP

O kapt (ferramenta de processamento de anotações do Kotlin) permite usar processadores de anotações Java com código Kotlin, mesmo que eles não tenham suporte específico para o Kotlin. Isso é feito gerando stubs Java dos arquivos Kotlin que podem ser lidos pelos processadores. Essa geração de stubs é uma operação cara e tem um impacto significativo na velocidade do build.

O KSP (Processamento de símbolos do Kotlin) é uma alternativa ao kapt que prioriza o Kotlin. O KSP analisa o código Kotlin diretamente, o que é até duas vezes mais rápido. Ele também entende melhor as construções da linguagem Kotlin.

É possível executar o kapt e o KSP simultaneamente durante a migração. Ela pode ser feita por módulo ou biblioteca.

Confira uma visão geral das etapas da migração:

  1. Conferir se as bibliotecas que você usa têm suporte ao KSP
  2. Adicionar o plug-in KSP ao projeto
  3. Substituir processadores de anotações pelo KSP
  4. Remover o plug-in kapt

Conferir se as bibliotecas que você usa têm suporte ao KSP

Para começar, confira se as bibliotecas que você está usando com o kapt já oferecem suporte ao KSP. Isso se aplica a muitas bibliotecas conhecidas, como Dagger, Glide, Room e Moshi, e outras estão adicionando suporte.

Confira a lista de bibliotecas com suporte na documentação. Também é possível consultar a documentação e o Issue Tracker das bibliotecas usadas.

Adicionar o plug-in KSP ao projeto

Primeiro, declare o plug-in KSP no arquivo build.gradle.kts de nível superior. Escolha uma versão do KSP alinhada à versão do Kotlin do seu projeto. Acesse uma lista de versões na página do GitHub da KSP (em inglês).

Kotlin

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

Groovy

plugins {
    id 'com.google.devtools.ksp' version '2.0.21-1.0.27' apply false
}

Em seguida, ative o KSP no arquivo build.gradle.kts do módulo:

Kotlin

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

Groovy

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

Substituir processadores de anotações pelo KSP

Com o KSP ativado, comece a substituir os usos do kapt por KSP. Para a maioria das bibliotecas, isso requer apenas a mudança do kapt para KSP na declaração de dependência, já que elas enviam o processador de anotações e o processador KSP no mesmo artefato.

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'
}

Depois de mudar para a KSP, sincronize e crie seu projeto para testar se ele ainda funciona corretamente.

Confira alguns problemas comuns:

  • Algumas bibliotecas não oferecem suporte ao mesmo conjunto de recursos com kapt e KSP. Se o código falhar após a migração, verifique a documentação da biblioteca.
  • O KSP tem informações do tipo Kotlin mais precisas do que o kapt (por exemplo, sobre nulidade). Isso significa que os processadores KSP podem ser mais precisos sobre os requisitos de tipo. Algumas correções no código-fonte podem ser necessárias, assim como a atualização dos arquivos de build.
  • Se você transmitia argumentos para o processador de anotações, provavelmente vai ser necessário transmiti-los para o KSP. Observe que o formato dos argumentos pode ser diferente entre o kapt e o KSP. Consulte a documentação do KSP (em inglês) e a da biblioteca usada para saber mais.

Remover o plug-in kapt

Quando você não tiver mais dependências incluídas com kapt no módulo, remova o plug-in kapt.

Se ela tiver sido declarada em um bloco de plug-ins, use este código:

Kotlin

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

Groovy

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

Se ela estava usando a sintaxe de aplicação do plug-in usando o Groovy:

apply plugin: 'kotlin-kapt'

Também é necessário remover qualquer configuração restante relacionada ao kapt, como:

Kotlin


kapt {
    correctErrorTypes = true
    useBuildCache = true
}

Groovy


kapt {
    correctErrorTypes true
    useBuildCache true
}

Outros recursos