Переход на встроенный Kotlin

Плагин Android Gradle 9.0 представляет встроенную поддержку Kotlin и включает её по умолчанию. Это означает, что вам больше не нужно применять плагин org.jetbrains.kotlin.android (или kotlin-android ) в файлах сборки для компиляции исходных файлов Kotlin. Благодаря встроенному Kotlin файлы сборки становятся проще, и вы можете избежать проблем совместимости между AGP и плагином kotlin-android .

Примечание: Встроенный Kotlin заменяет только плагин kotlin-android . Если вы пишете модуль библиотеки Kotlin Multiplatform (KMP), вам всё равно необходимо применить плагины org.jetbrains.kotlin.multiplatform и com.android.kotlin.multiplatform.library . Кроме того, использование плагина org.jetbrains.kotlin.multiplatform вместе с плагином com.android.library или com.android.application больше не допускается при включённом встроенном Kotlin.

Включить встроенный Kotlin

Для встроенной поддержки Kotlin требуется AGP 9.0 или выше. AGP 9.0 уже включает встроенную поддержку Kotlin для всех ваших модулей, где применяется AGP, поэтому вам не нужно ничего делать для её включения. Однако, если вы ранее отказались от встроенной поддержки Kotlin , установив параметр android.builtInKotlin=false в файле gradle.properties , вам необходимо удалить этот параметр или установить его в true .

Примечание: Вы также можете включить встроенный Kotlin для одного модуля за раз .

Встроенный Kotlin требует внесения некоторых изменений в ваш проект, поэтому после включения встроенного Kotlin выполните следующие шаги для миграции вашего проекта.

Этапы миграции

После обновления проекта со старой версии AGP до AGP 9.0 или после ручного включения встроенного Kotlin вы можете увидеть следующее сообщение об ошибке:

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

...или

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.

Эта ошибка возникает, поскольку встроенный Kotlin требует внесения изменений в ваш проект. Чтобы устранить эту ошибку, выполните следующие действия:

Примечание: если вы еще не готовы перенести свой проект, вы также можете отказаться от встроенного Kotlin .

1. Удалить плагин kotlin-android
2. При необходимости перенесите плагин kotlin-kapt
3. При необходимости перенесите DSL android.kotlinOptions{}
4. При необходимости перенесите DSL kotlin.sourceSets{}

1. Удалите плагин kotlin-android

Удалите плагин org.jetbrains.kotlin.android (или kotlin-android ) из файлов сборки на уровне модуля, где вы его применяете. Точный код для удаления зависит от того, используете ли вы каталоги версий для объявления плагинов.

С каталогами версий

Котлин

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

Затем удалите плагин из файла сборки верхнего уровня:

С каталогами версий

Котлин

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

Если вы используете каталоги версий, также удалите определение плагина из файла TOML каталога версий (обычно gradle/libs.versions.toml ):

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

2. При необходимости перенесите плагин kotlin-kapt

Плагин org.jetbrains.kotlin.kapt (или kotlin-kapt ) несовместим со встроенным Kotlin. Если вы используете kapt , рекомендуем перенести свой проект на KSP .

Если вы пока не можете перейти на KSP, замените плагин kotlin-kapt на плагин com.android.legacy-kapt , используя ту же версию, что и ваш плагин Android Gradle.

Например, с помощью каталогов версий обновите файл TOML каталога версий следующим образом:

[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" }

Затем обновите файлы сборки:

Котлин

// 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)
}

Примечание: Если вы объявляете плагин kotlin-kapt в блоке plugins{} как kotlin("kapt") version "<KOTLIN_VERSION>" , то удалите эту строку.

3. При необходимости перенесите DSL android.kotlinOptions{}

Если вы используете android.kotlinOptions{} DSL, вам необходимо перенести его в kotlin.compilerOptions{} DSL.

Например, обновите этот код:

Котлин

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

Круто

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

...к новому 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
    }
}

Примечание: при использовании встроенного Kotlin вам не нужно устанавливать kotlin.compilerOptions.jvmTarget , поскольку его значение по умолчанию равно android.compileOptions.targetCompatibility .

4. При необходимости перенесите DSL kotlin.sourceSets{}

При использовании плагина kotlin-android AGP позволяет добавлять дополнительные каталоги исходного кода Kotlin с помощью DSL-класса android.sourceSets{} или kotlin.sourceSets{} . С помощью DSL-класса android.sourceSets{} можно добавлять каталоги либо в набор AndroidSourceSet.kotlin , либо в набор AndroidSourceSet.java .

При использовании встроенного Kotlin единственный поддерживаемый вариант — добавить каталоги в набор AndroidSourceSet.kotlin с помощью DSL-класса android.sourceSets{} . Если вы используете неподдерживаемые варианты, выполните миграцию следующим образом:

Котлин

# 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"
}

Круто

# 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")
}

Если вы хотите добавить исходный каталог Kotlin к определенному варианту или если каталог создается задачей, вы можете использовать методы addStaticSourceDirectory или addGeneratedSourceDirectory в API варианта :

Котлин

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

Круто

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

Сообщить о проблемах

Если после выполнения предыдущих шагов у вас возникли проблемы, ознакомьтесь с известными проблемами в проблеме № 438678642 и при необходимости отправьте нам отзыв.

Отказаться от встроенного Kotlin

Если вам не удаётся перевести проект на использование встроенного Kotlin, установите android.builtInKotlin=false в файле gradle.properties , чтобы временно отключить его. После этого сборка выдаст предупреждение с напоминанием о необходимости перейти на встроенный Kotlin, поскольку отключить встроенный Kotlin в будущих версиях AGP 9.x, предшествующих AGP 10.0, будет невозможно.

Примечание: Вам также необходимо установить android.newDsl=false , чтобы отказаться от нового DSL, поскольку плагин kotlin-android несовместим с ним.

Когда вы будете готовы перенести свой проект, включите встроенный Kotlin и следуйте инструкциям по миграции .

Миграция по модулям

Свойство Gradle android.builtInKotlin позволяет включать или отключать встроенный Kotlin для всех ваших модулей, где вы применяете AGP.

Если перенос всех модулей одновременно вызывает затруднения, вы можете переносить модули по одному за раз:

1. Установите android.builtInKotlin=false в файле gradle.properties , чтобы отключить встроенный Kotlin для всех модулей.

2. Примените плагин com.android.built-in-kotlin к модулю, в котором вы хотите включить встроенный Kotlin, используя ту же версию, что и ваш плагин Android Gradle.

3. Выполните предыдущие шаги по миграции , чтобы перенести этот модуль во встроенный Kotlin.

4. После переноса всех модулей удалите настройку android.builtInKotlin=false в файле gradle.properties и плагин com.android.built-in-kotlin в файлах сборки.

Возможность выборочного отключения встроенного Kotlin

Плагин Gradle для Android 9.0 включает встроенный Kotlin для всех модулей, где он применяется. Мы рекомендуем выборочно отключать встроенный Kotlin для модулей без исходного кода Kotlin в крупных проектах. Это устраняет как задачу компиляции Kotlin, которая немного снижает производительность сборки, так и автоматическую зависимость от стандартной библиотеки Kotlin.

Чтобы отключить встроенный Kotlin для модуля, установите enableKotlin = false в файле сборки этого модуля:

Котлин

android {
    enableKotlin = false
}

Круто

android {
    enableKotlin = false
}