به کوتلین داخلی مهاجرت کنید

افزونه‌ی اندروید گریدل ۹.۰ پشتیبانی داخلی از کاتلین را معرفی کرده و آن را به طور پیش‌فرض فعال می‌کند. این بدان معناست که دیگر لازم نیست افزونه‌ی org.jetbrains.kotlin.android (یا kotlin-android ) را در فایل‌های ساخت خود برای کامپایل فایل‌های منبع کاتلین اعمال کنید. با کاتلین داخلی، فایل‌های ساخت شما ساده‌تر می‌شوند و می‌توانید از مشکلات سازگاری بین AGP و افزونه‌ی kotlin-android جلوگیری کنید.

فعال کردن کاتلین داخلی

برای پشتیبانی از کاتلین داخلی به AGP 9.0 یا بالاتر نیاز دارید. AGP 9.0 از قبل کاتلین داخلی را برای تمام ماژول‌های شما که AGP را اعمال می‌کنید، فعال می‌کند، بنابراین نیازی به انجام کاری برای فعال کردن آن ندارید. با این حال، اگر قبلاً با تنظیم android.builtInKotlin=false در فایل gradle.properties از کاتلین داخلی انصراف داده‌اید ، باید آن تنظیم را حذف کنید یا آن را روی true تنظیم کنید.

کاتلین داخلی نیاز به تغییراتی در پروژه شما دارد، بنابراین پس از فعال کردن کاتلین داخلی، مراحل بعدی را برای مهاجرت پروژه خود دنبال کنید.

مراحل مهاجرت

بعد از اینکه پروژه خود را از نسخه قدیمی‌تر 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.

این خطا به این دلیل رخ می‌دهد که کاتلین داخلی نیاز به تغییراتی در پروژه شما دارد. برای رفع این خطا، مراحل زیر را دنبال کنید:

  1. افزونه kotlin-android را حذف کنید
  2. در صورت لزوم، افزونه kotlin-kapt را منتقل کنید
  3. در صورت لزوم android.kotlinOptions{} DSL را منتقل کنید
  4. در صورت لزوم kotlin.sourceSets{} DSL را منتقل کنید.

۱. افزونه‌ی 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" }

۲. در صورت لزوم، افزونه kotlin-kapt را منتقل کنید

افزونه‌ی org.jetbrains.kotlin.kapt (یا kotlin-kapt ) با کاتلینِ پیش‌فرض سازگار نیست. اگر 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)
}

۳. در صورت لزوم android.kotlinOptions{} DSL را منتقل کنید.

اگر از 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.sourceSets{} DSL را منتقل کنید

وقتی از افزونه kotlin-android استفاده می‌کنید، AGP به شما امکان می‌دهد دایرکتوری‌های منبع Kotlin اضافی را با استفاده از android.sourceSets{} DSL یا kotlin.sourceSets{} DSL اضافه کنید. با android.sourceSets{} DSL، می‌توانید دایرکتوری‌ها را به مجموعه AndroidSourceSet.kotlin یا مجموعه AndroidSourceSet.java اضافه کنید.

با کاتلین داخلی، تنها گزینه پشتیبانی‌شده، اضافه کردن دایرکتوری‌ها به مجموعه AndroidSourceSet.kotlin با استفاده از android.sourceSets{} DSL است. اگر از گزینه‌های پشتیبانی‌نشده استفاده می‌کنید، آن‌ها را به صورت زیر منتقل کنید:

کاتلین 

# 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 را به یک variant خاص اضافه کنید یا اگر دایرکتوری توسط یک task ایجاد شده باشد، می‌توانید از متدهای addStaticSourceDirectory یا addGeneratedSourceDirectory در API variant استفاده کنید:

کاتلین 

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

گزارش مشکلات

اگر پس از انجام مراحل قبلی با مشکلی مواجه شدید، مشکلات شناخته‌شده در شماره #۴۳۸۶۷۸۶۴۲ را بررسی کنید و در صورت نیاز به ما بازخورد دهید.

از کاتلین داخلی صرف نظر کنید

اگر نمی‌توانید پروژه خود را به کاتلین داخلی منتقل کنید، در فایل gradle.properties مقدار android.builtInKotlin=false را برای غیرفعال کردن موقت آن تنظیم کنید. وقتی این کار را انجام می‌دهید، هنگام ساخت، هشداری نمایش داده می‌شود که به شما یادآوری می‌کند به کاتلین داخلی مهاجرت کنید، زیرا در نسخه‌های بعدی AGP 9.x قبل از AGP 10.0 نمی‌توانید کاتلین داخلی را غیرفعال کنید.

زمانی که آماده‌ی مهاجرت پروژه‌ی خود شدید، کاتلین داخلی را فعال کنید و مراحل مهاجرت را دنبال کنید.

مهاجرت ماژول به ماژول

ویژگی android.builtInKotlin Gradle به شما امکان می‌دهد کاتلین داخلی را برای تمام ماژول‌های خود که در آن‌ها AGP اعمال می‌کنید، فعال یا غیرفعال کنید.

اگر انتقال همه ماژول‌ها به طور همزمان چالش برانگیز است، می‌توانید هر بار یک ماژول را انتقال دهید:

  1. در فایل gradle.properties مقدار android.builtInKotlin=false را تنظیم کنید تا کاتلین داخلی برای همه ماژول‌ها غیرفعال شود.

  2. افزونه‌ی com.android.built-in-kotlin را روی ماژولی که می‌خواهید کاتلین داخلی را فعال کنید، اعمال کنید. این کار را با استفاده از همان نسخه افزونه‌ی اندروید Gradle انجام دهید.

  3. برای انتقال این ماژول به کاتلین داخلی، مراحل مهاجرت قبلی را دنبال کنید.

  4. پس از انتقال تمام ماژول‌هایتان، تنظیمات android.builtInKotlin=false را در gradle.properties و افزونه com.android.built-in-kotlin را در فایل‌های ساخت خود حذف کنید.

گزینه‌ای برای غیرفعال کردن انتخابی کاتلین داخلی

افزونه‌ی اندروید گریدل ۹.۰، کاتلین داخلی را برای تمام ماژول‌هایی که در آن‌ها اعمال می‌شود، فعال می‌کند. توصیه می‌کنیم کاتلین داخلی را به صورت انتخابی برای ماژول‌هایی که منابع کاتلین ندارند، در پروژه‌های بزرگ غیرفعال کنید. این کار هم وظیفه‌ی کامپایل کاتلین را که هزینه‌ی عملکرد ساخت کمی دارد و هم وابستگی خودکار به کتابخانه‌ی استاندارد کاتلین را حذف می‌کند.

برای غیرفعال کردن کاتلین داخلی برای یک ماژول، در فایل ساخت آن ماژول، enableKotlin = false را تنظیم کنید:

کاتلین 

android {
    enableKotlin = false
}

گرووی 

android {
    enableKotlin = false
}