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.

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 android.builtInKotlin=true para ativar.

O Kotlin integrado exige que você faça 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.

Isso porque o Kotlin integrado exige que você faça algumas mudanças no seu projeto. Para resolver esse erro, siga estas etapas:

1. Remover o plug-in kotlin-android
2. Migre o plug-in kotlin-kapt, se necessário
3. Migre o bloco kotlinOptions{}, 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ê está usando catálogos de versões para declarar plug-ins.

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

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

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

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

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

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

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

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

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

Se você estiver usando 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

Se você estiver usando org.jetbrains.kotlin.kapt (ou kotlin-kapt) nos arquivos de build, esse plug-in não será compatível com o Kotlin integrado. Você precisa substituir esse plug-in pelo com.android.legacy-kapt, usando a mesma versão do seu Plug-in do Android para Gradle atual.

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:

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

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

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

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

3. Migrar o bloco kotlinOptions{}, se necessário

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

Por exemplo, atualize este código:

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

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

...para a nova DSL:

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

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

Relatar problemas

Depois de concluir as etapas anteriores, se você encontrar problemas, confira os problemas conhecidos na descrição do 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 desativar temporariamente o Kotlin integrado. 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.

Migração módulo por módulo

A propriedade android.builtInKotlin do Gradle permite ativar ou desativar o Kotlin integrado em 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.experimental.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 atual.

3. Siga as etapas de migração anteriores para migrar esse módulo para o 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.experimental.built-in-kotlin nos arquivos de build.