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

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

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

برای پشتیبانی از کاتلین داخلی به AGP 9.0 یا بالاتر نیاز دارید. AGP 9.0 از قبل کاتلین داخلی را برای تمام ماژول‌های شما که AGP را اعمال می‌کنید، فعال می‌کند، بنابراین نیازی به انجام کاری برای فعال کردن آن ندارید. با این حال، اگر قبلاً با تنظیم android.builtInKotlin=false در فایل gradle.properties از کاتلین داخلی انصراف داده‌اید ، باید آن تنظیم را حذف کنید یا android.builtInKotlin=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. در صورت لزوم، بلوک kotlinOptions{} را منتقل کنید.

۱. افزونه‌ی 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 ) در فایل‌های ساخت خود استفاده می‌کنید، این افزونه با کاتلین داخلی سازگار نخواهد بود. توصیه می‌کنیم پروژه خود را به 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)
}

۳. در صورت لزوم، بلوک 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
    }
}

گزارش مشکلات

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

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

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

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

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

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

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

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

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

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

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