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

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

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

ملاحظة: يمكنك أيضًا تفعيل Kotlin المضمّنة لوحدة واحدة في كل مرة.

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

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

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

‫1. إزالة المكوّن الإضافي "kotlin-android"

أزِل المكوّن الإضافي org.jetbrains.kotlin.android (أو kotlin-android) من ملفات التصميم على مستوى الوحدة التي تستخدمه فيها. يعتمد الرمز الدقيق الذي يجب إزالته على ما إذا كنت تستخدم كتالوجات الإصدارات لتحديد المكوّنات الإضافية.

باستخدام كتالوجات الإصدارات

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

ما مِن كتالوجات إصدارات

Kotlin

// Module-level build file
plugins {
    id("org.jetbrains.kotlin.android")
}

Groovy

// Module-level build file
plugins {
    id 'org.jetbrains.kotlin.android'
}

بعد ذلك، أزِل المكوّن الإضافي من ملف الإصدار ذي المستوى الأعلى:

باستخدام كتالوجات الإصدارات

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

ما مِن كتالوجات إصدارات

Kotlin

// Top-level build file
plugins {
    id("org.jetbrains.kotlin.android") version "KOTLIN_VERSION" apply false
}

Groovy

// 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، ننصحك بنقل مشروعك إلى "منصة خدمات Google".

إذا تعذّر عليك نقل البيانات إلى 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" }

بعد ذلك، عدِّل ملفات الإصدار على النحو التالي:

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

ملاحظة: إذا أعلنت عن المكوّن الإضافي kotlin-kapt في الحظر plugins{} على أنّه kotlin("kapt") version "<KOTLIN_VERSION>"، عليك إزالة هذا السطر بدلاً من ذلك.

3- نقل android.kotlinOptions{} DSL إذا لزم الأمر

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

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

Kotlin

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

Groovy

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

...إلى لغة DSL الجديدة:

Kotlin

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Groovy

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- نقل kotlin.sourceSets{} DSL إذا لزم الأمر

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

باستخدام Kotlin المضمّنة، الخيار الوحيد المتاح هو إضافة الأدلة إلى مجموعة AndroidSourceSet.kotlin باستخدام android.sourceSets{} DSL. في حال استخدام خيارات غير متوافقة، يمكنك نقلها باتّباع الخطوات التالية:

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 += "additionalSourceDirectory/kotlin"
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

Groovy

# 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 في واجهة برمجة التطبيقات الخاصة بالصيغة:

Kotlin

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

Groovy

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 المضمّنة في إصدار مستقبلي من الإصدار 9.x من Android Gradle Plugin قبل الإصدار 10.0 من Android Gradle Plugin.

ملاحظة: عليك أيضًا ضبط android.newDsl=false لإيقاف DSL الجديد لأنّ المكوّن الإضافي kotlin-android غير متوافق معه.

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

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

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

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

1. اضبط android.builtInKotlin=false في ملف gradle.properties على false لإيقاف 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 في ملف الإصدار الخاص بهذه الوحدة:

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}