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

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

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

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

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

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

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 داخلی سازگار نخواهد بود. باید این افزونه را با افزونه 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)
}

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

مشکلات را گزارش کنید

پس از انجام مراحل قبلی، اگر با مشکل مواجه شدید، مشکلات شناخته شده را در شرح شماره 438678642 بررسی کنید و در صورت نیاز بازخورد خود را به ما ارائه دهید.

انصراف از Kotlin داخلی

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

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

ویژگی android.builtInKotlin Gradle به شما امکان می دهد Kotlin داخلی را برای همه ماژول های خود در جایی که AGP اعمال می کنید فعال یا غیرفعال کنید.

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

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

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

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

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