Migrar para o Kotlin integrado

O Plug-in do Android para Gradle 9.0 introduz a compatibilidade integrada com Kotlin e a ativa por padrão. Isso significa que você não precisa mais aplicar o plug-in org.jetbrains.kotlin.android (ou kotlin-android) nos arquivos de build para compilar arquivos de origem Kotlin. Com o Kotlin integrado, os arquivos de build são mais simples, e você evita problemas de compatibilidade entre o AGP e o plug-in kotlin-android.

Observação: o Kotlin integrado substitui apenas o plug-in kotlin-android. Se você estiver escrevendo um módulo de biblioteca do Kotlin Multiplatform (KMP), ainda precisará aplicar o plug-in org.jetbrains.kotlin.multiplatform e o plug-in com.android.kotlin.multiplatform.library. Além disso, não é mais permitido usar o plug-in org.jetbrains.kotlin.multiplatform com o com.android.library ou com.android.application quando o Kotlin integrado está ativado.

Ativar o Kotlin integrado

Você precisa do AGP 9.0 ou de uma versão mais recente para ter suporte integrado ao Kotlin. O AGP 9.0 já ativa o Kotlin integrado em todos os módulos em que você aplica o AGP. Portanto, não é necessário fazer nada para ativar. No entanto, se você tiver desativado o Kotlin integrado definindo android.builtInKotlin=false no arquivo gradle.properties, remova essa configuração ou defina como true.

Observação: também é possível ativar o Kotlin integrado para um módulo por vez.

O Kotlin integrado exige algumas mudanças no projeto. Portanto, depois de ativar o Kotlin integrado, siga as próximas etapas para migrar o projeto.

Etapas da migração

Depois de fazer upgrade do seu projeto de uma versão mais antiga do AGP para o AGP 9.0 ou depois de ativar manualmente o Kotlin integrado, talvez você veja a seguinte mensagem de erro:

Failed to apply plugin 'org.jetbrains.kotlin.android'.
> Cannot add extension with name 'kotlin', as there is an extension already registered with that name.

...ou

Failed to apply plugin 'com.jetbrains.kotlin.android'
> The 'org.jetbrains.kotlin.android' plugin is no longer required for Kotlin support since AGP 9.0.

Esse erro ocorre porque o Kotlin integrado exige algumas mudanças no projeto. Para resolver esse erro, siga estas etapas:

Observação: se você ainda não estiver pronto para migrar seu projeto, também poderá desativar o Kotlin integrado.

1. Remover o plug-in kotlin-android
2. Migre o plug-in kotlin-kapt, se necessário
3. Migre a DSL android.kotlinOptions{}, se necessário
4. Migre a DSL kotlin.sourceSets{}, se necessário

1. Remover o plug-in kotlin-android

Remova o plug-in org.jetbrains.kotlin.android (ou kotlin-android) dos arquivos de build no nível do módulo em que ele é aplicado. O código exato a ser removido depende de se você usa catálogos de versões para declarar plug-ins.

Com catálogos de versões

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Nenhum catálogo de versões

Kotlin

// Module-level build file
plugins {
    id("org.jetbrains.kotlin.android")
}

Groovy

// Module-level build file
plugins {
    id 'org.jetbrains.kotlin.android'
}

Em seguida, remova o plug-in do arquivo de build de nível superior:

Com catálogos de versões

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Nenhum catálogo de versões

Kotlin

// Top-level build file
plugins {
    id("org.jetbrains.kotlin.android") version "KOTLIN_VERSION" apply false
}

Groovy

// Top-level build file
plugins {
    id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false
}

Se você usa catálogos de versões, remova também a definição do plug-in do arquivo TOML do catálogo de versões (geralmente gradle/libs.versions.toml):

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "KOTLIN_VERSION" }

2. Migrar o plug-in kotlin-kapt, se necessário

O plug-in org.jetbrains.kotlin.kapt (ou kotlin-kapt) é incompatível com o Kotlin integrado. Se você usa kapt, recomendamos que migre seu projeto para o KSP.

Se você ainda não puder migrar para o KSP, substitua o plug-in kotlin-kapt pelo com.android.legacy-kapt, usando a mesma versão do plug-in do Android Gradle.

Por exemplo, com catálogos de versões, atualize o arquivo TOML do catálogo de versões da seguinte maneira:

[plugins]
android-application = { id = "com.android.application", version.ref = "AGP_VERSION" }

# Add the following plugin definition
legacy-kapt = { id = "com.android.legacy-kapt", version.ref = "AGP_VERSION" }

# Remove the following plugin definition
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "KOTLIN_VERSION" }

Em seguida, atualize os arquivos de build:

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Observação: se você declarar o plug-in kotlin-kapt no bloco plugins{} como kotlin("kapt") version "<KOTLIN_VERSION>", remova essa linha.

3. Migre a DSL android.kotlinOptions{}, se necessário.

Se você usa a DSL android.kotlinOptions{}, migre para a DSL kotlin.compilerOptions{}.

Por exemplo, atualize este código:

Kotlin

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

Groovy

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

...para a nova DSL:

Kotlin

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Groovy

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Observação: com o Kotlin integrado, não é necessário definir kotlin.compilerOptions.jvmTarget porque o valor padrão é android.compileOptions.targetCompatibility.

4. Migre a DSL kotlin.sourceSets{}, se necessário.

Ao usar o plug-in kotlin-android, o AGP permite adicionar outros diretórios de origem do Kotlin usando a DSL android.sourceSets{} ou a DSL kotlin.sourceSets{}. Com a DSL android.sourceSets{}, é possível adicionar os diretórios ao conjunto AndroidSourceSet.kotlin ou AndroidSourceSet.java.

Com o Kotlin integrado, a única opção compatível é adicionar os diretórios ao conjunto AndroidSourceSet.kotlin usando a DSL android.sourceSets{}. Se você usa opções sem suporte, migre-as da seguinte maneira:

Kotlin

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories += "additionalSourceDirectory/kotlin"
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

Groovy

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories.add("additionalSourceDirectory/kotlin")
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories.add("additionalSourceDirectory/kotlin")
}

Se você quiser adicionar um diretório de origem Kotlin a uma variante específica ou se o diretório for gerado por uma tarefa, use os métodos addStaticSourceDirectory ou addGeneratedSourceDirectory na API de variantes:

Kotlin

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Groovy

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Relatar problemas

Se você encontrar problemas depois de concluir as etapas anteriores, analise os problemas conhecidos em problema nº 438678642 e envie feedback se necessário.

Desativar o Kotlin integrado

Se não for possível migrar seu projeto para usar o Kotlin integrado, defina android.builtInKotlin=false no arquivo gradle.properties para desativá-lo temporariamente. Quando você faz isso, o build mostra um aviso lembrando de migrar para o Kotlin integrado, já que não será possível desativá-lo em uma versão futura do AGP 9.x antes do AGP 10.0.

Observação: também é necessário definir android.newDsl=false para desativar a nova DSL porque o plug-in kotlin-android não é compatível com ela.

Quando estiver tudo pronto para migrar seu projeto, ative o Kotlin integrado e siga as etapas de migração.

Migração módulo por módulo

A propriedade android.builtInKotlin do Gradle permite ativar ou desativar o Kotlin integrado para todos os módulos em que você aplica o AGP.

Se migrar todos os módulos de uma vez for difícil, faça isso um de cada vez:

1. Defina android.builtInKotlin=false no arquivo gradle.properties para desativar o Kotlin integrado em todos os módulos.

2. Aplique o plug-in com.android.built-in-kotlin ao módulo em que você quer ativar o Kotlin integrado, usando a mesma versão do seu plug-in do Android para Gradle.

3. Siga as etapas de migração anteriores para migrar esse módulo para Kotlin integrado.

4. Depois de migrar todos os módulos, remova a configuração android.builtInKotlin=false em gradle.properties e o plug-in com.android.built-in-kotlin nos arquivos de build.

Opção para desativar seletivamente o Kotlin integrado

O Plug-in do Android para Gradle 9.0 ativa o Kotlin integrado em todos os módulos em que ele é aplicado. Recomendamos desativar o Kotlin integrado de forma seletiva para módulos que não têm fontes Kotlin em projetos grandes. Isso remove a tarefa de compilação do Kotlin, que tem um pequeno custo de desempenho de build, e a dependência automática da biblioteca padrão do Kotlin.

Para desativar o Kotlin integrado em um módulo, defina enableKotlin = false no arquivo de build desse módulo:

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}