نقل البيانات إلى Kotlin المضمّنة

يقدّم الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android دعمًا مدمجًا للغة Kotlin ويفعّله تلقائيًا. هذا يعني أنّه لم يعُد عليك تطبيق المكوّن الإضافي org.jetbrains.kotlin.android (أو kotlin-android) في ملفات التصميم لتجميع ملفات مصدر Kotlin. باستخدام Kotlin المدمجة، تصبح ملفات التصميم أبسط ويمكنك تجنُّب مشاكل التوافق بين المكوّن الإضافي لنظام Gradle المتوافق مع Android والمكوّن الإضافي kotlin-android.

تفعيل Kotlin المدمجة

تحتاج إلى الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android أو إصدار أحدث للحصول على دعم Kotlin المدمجة. يفعّل الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android Kotlin المدمجة تلقائيًا لجميع الوحدات التي تطبّق فيها المكوّن الإضافي لنظام Gradle المتوافق مع Android، لذا ليس عليك اتّخاذ أي إجراء لتفعيلها. ومع ذلك، إذا سبق لك إيقاف Kotlin المدمجة من خلال ضبط android.builtInKotlin=false في ملف gradle.properties، عليك إزالة هذا الإعداد أو ضبطه على true.

تتطلّب Kotlin المدمجة إجراء بعض التغييرات على مشروعك، لذا بعد تفعيل Kotlin المدمجة، اتّبِع الخطوات التالية لنقل بيانات مشروعك.

خطوات نقل البيانات

بعد ترقية مشروعك من إصدار أقدم من المكوّن الإضافي لنظام Gradle المتوافق مع Android إلى الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android أو بعد تفعيل 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. نقل بيانات لغة النطاق الخاصة باللغة android.kotlinOptions{} إذا لزم الأمر
4. نقل بيانات لغة النطاق الخاصة باللغة 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، باستخدام الإصدار نفسه من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

على سبيل المثال، باستخدام كتالوجات الإصدارات، عدِّل ملف 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. نقل بيانات لغة النطاق الخاصة باللغة android.kotlinOptions{} إذا لزم الأمر

إذا كنت تستخدم لغة النطاق الخاصة باللغة android.kotlinOptions{}، عليك نقل بياناتها إلى لغة النطاق الخاصة باللغة kotlin.compilerOptions{}.

على سبيل المثال، عدِّل هذا الرمز:

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

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "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 {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

‫4. نقل بيانات لغة النطاق الخاصة باللغة kotlin.sourceSets{} إذا لزم الأمر

عند استخدام المكوّن الإضافي kotlin-android، يتيح لك المكوّن الإضافي لنظام Gradle المتوافق مع Android إضافة أدلة مصدر Kotlin إضافية باستخدام لغة النطاق الخاصة باللغة android.sourceSets{} أو لغة النطاق الخاصة باللغة kotlin.sourceSets{}. باستخدام لغة النطاق الخاصة باللغة android.sourceSets{}، يمكنك إضافة الأدلة إلى مجموعة AndroidSourceSet.kotlin أو مجموعة AndroidSourceSet.java.

باستخدام Kotlin المدمجة، الخيار الوحيد المتاح هو إضافة الأدلة إلى مجموعة AndroidSourceSet.kotlin باستخدام لغة النطاق الخاصة باللغة 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 الطريقتَين في واجهة برمجة التطبيقات الخاصة بالتنويعة:

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 المدمجة في الإصدار 10.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

بعد أن تصبح مستعدًا لنقل بيانات مشروعك، فعِّل Kotlin المدمجة واتّبِع خطوات نقل البيانات.

نقل البيانات على مستوى الوحدة

تتيح لك سمة Gradle android.builtInKotlin تفعيل Kotlin المدمجة أو إيقافها لجميع الوحدات التي تطبّق فيها المكوّن الإضافي لنظام Gradle المتوافق مع Android.

إذا كان نقل بيانات جميع الوحدات في وقت واحد أمرًا صعبًا، يمكنك نقل بيانات وحدة واحدة في كل مرة:

1. اضبط android.builtInKotlin=false في ملف gradle.properties لإيقاف Kotlin المدمجة لجميع الوحدات.

2. طبِّق المكوّن الإضافي com.android.built-in-kotlin على الوحدة التي تريد تفعيل Kotlin المدمجة فيها، باستخدام الإصدار نفسه من المكوّن الإضافي لنظام Gradle المتوافق مع Android.

3. اتّبِع خطوات نقل البيانات السابقة لنقل بيانات هذه الوحدة إلى Kotlin المدمجة.

4. بعد نقل بيانات جميع الوحدات، أزِل الإعداد android.builtInKotlin=false في gradle.properties والمكوّن الإضافي com.android.built-in-kotlin في ملفات التصميم.

خيار إيقاف Kotlin المدمجة بشكل انتقائي

يفعّل الإصدار 9.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android Kotlin المدمجة لجميع الوحدات التي يتم تطبيقها فيها. ننصحك بإيقاف Kotlin المدمجة بشكل انتقائي للوحدات التي لا تتضمّن مصادر Kotlin في المشاريع الكبيرة. يؤدي ذلك إلى إزالة كلّ من مهمة تجميع Kotlin، التي تتكبّد تكلفة صغيرة على أداء التصميم، والاعتماد التلقائي على مكتبة Kotlin العادية.

لإيقاف Kotlin المدمجة لوحدة، اضبط enableKotlin = false في ملف تصميم تلك الوحدة:

android {
    enableKotlin = false
}

android {
    enableKotlin = false
}