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

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

تفعيل Kotlin المضمّنة

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

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

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

بعد ترقية مشروعك من إصدار قديم من "مكوّن Android الإضافي لنظام Gradle" إلى الإصدار 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) من ملفات الإصدار على مستوى الوحدة التي تستخدمه فيها. يعتمد الرمز البرمجي المطلوب إزالته على ما إذا كنت تستخدم كتالوجات الإصدارات لتحديد الإضافات.

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

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 المضمّنة. عليك استبدال هذا المكوّن الإضافي بالمكوّن الإضافي 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)
}

3- نقل المربّع kotlinOptions{} إذا لزم الأمر

إذا كنت تستخدم لغة النطاق الخاص 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
    }
}

الإبلاغ عن المشاكل

بعد إكمال الخطوات السابقة، إذا واجهت مشاكل، يمكنك الاطّلاع على المشاكل المعروفة في وصف المشكلة رقم 438678642 وإرسال ملاحظاتك إلينا إذا لزم الأمر.

إيقاف استخدام Kotlin المضمّنة

إذا لم تتمكّن من نقل مشروعك لاستخدام Kotlin المضمّنة، اضبط android.builtInKotlin = false في ملف gradle.properties لإيقاف Kotlin المضمّنة مؤقتًا. عند إجراء ذلك، سيعرض الإصدار تحذيرًا يذكّرك بنقل البيانات إلى Kotlin المضمّنة لأنّه لن يكون بإمكانك إيقاف Kotlin المضمّنة في إصدار مستقبلي من الإصدار 9.x من AGP قبل الإصدار 10.0 من AGP.

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

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

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

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

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

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

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