Kotlin Academy · درس

دمج معالجات KSP في عملية بناء Gradle

اضبط KSP في Gradle وأضف المصادر المُنشأة وصحّح مخرجات المعالج.

دمج معالجات KSP في عملية بناء Gradle درس مجاني في Kotlin Academy على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Kotlin Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

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

يتضمن إعداد KSP النموذجي وحدتين على الأقل: :annotation (يحتوي على فئات التعليقات التوضيحية) و:processor (يحتوي على SymbolProcessor). تطبّق الوحدة المستهلكة إضافة KSP وتُعلن عن تبعيات ksp وimplementation.

تطبيق إضافة KSP

في ملف build.gradle.kts الخاص بالوحدة المستهلكة:

plugins {
    kotlin("jvm")  // or android, multiplatform
    id("com.google.devtools.ksp") version "2.0.0-1.0.21"
}

تعريف تبعية ksp

استخدم إعداد ksp (وليس implementation) لإضافة معالج KSP. يعمل المعالج أثناء البناء فقط، ولا يُضمَّن في الأثر النهائي:

dependencies {
    implementation(project(":annotation"))
    ksp(project(":processor"))
}

أدلة المصدر المُولَّد

يكتب KSP الملفات المُولَّدة ضمن build/generated/ksp/<sourceSet>/kotlin/. وتضيف إضافة KSP هذه الأدلة تلقائيًا إلى مجموعة مصادر Kotlin، لذلك تكون الفئات المُولَّدة مرئية للتعليمات البرمجية من دون إعداد يدوي.

تمرير الخيارات إلى المعالج

مرّر خيارات وقت البناء من Gradle إلى المعالج باستخدام ksp { arg("key", "value") }. واقرأها في المعالج باستخدام environment.options["key"]:

// build.gradle.kts (consumer)
ksp {
    arg("generateMocks", "true")
    arg("outputPackage", "com.example.generated")
}

قراءة الخيارات في المعالج

في الأسلوب SymbolProcessorProvider.create()، يمكنك الوصول إلى الخيارات من البيئة:

class MyProcessorProvider : SymbolProcessorProvider {
    override fun create(environment: SymbolProcessorEnvironment): SymbolProcessor {
        val genMocks = environment.options["generateMocks"] == "true"
        return MyProcessor(environment.codeGenerator, environment.logger, genMocks)
    }
}

البناء التزايدي

يتتبع KSP تبعيات المدخلات والمخرجات. اربط كل ملف مُولَّد برموز مصدره عند استدعاء codeGenerator.createNewFile(). بعد ذلك، يتخطى KSP إعادة المعالجة عندما لا يتغير أي من المدخلات التي يتتبعها.

val deps = Dependencies(aggregating = false, *symbols.map { it.containingFile!! }.toTypedArray())
codeGenerator.createNewFile(deps, packageName, fileName)

استخدام KSP مع Android

في مشاريع Android، استبدل kapt بـ ksp في كلٍّ من تعريف الإضافة وتعريفات التبعيات. استخدم إعدادات تراعي نوع البناء، مثل kspDebug أو kspRelease، إذا احتجت إلى اختلاف سلوك المعالج بين أنواع البناء.

استخدام KSP مع Kotlin Multiplatform

في مشروع KMP، طبّق إضافة KSP واستخدم add(kotlinCompilation.defaultSourceSetName + "ksp", project(":processor")) أو الاختصار kspCommonMainMetadata أو kspJvmMain وغيرهما، وفقًا للأهداف التي يدعمها المعالج.

عرض الملفات المُولَّدة

بعد تشغيل ./gradlew build (أو kspKotlin / kspDebugKotlin لنظام Android)، افحص build/generated/ksp/. يعلّم IntelliJ وAndroid Studio هذه المجلدات كمصادر مُولَّدة، ويتيحان الانتقال من مواضع الاستخدام إلى التعريفات المُولَّدة.

تصحيح أخطاء المعالج

شغّل مهمة Gradle باستخدام --debug، أو أضف jvmArgs("-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005") إلى إعداد ksp لإرفاق مصحح أخطاء عن بُعد بآلة JVM الافتراضية لمعالجة التعليقات التوضيحية.

تحقق سريع

ما إعداد Gradle المستخدم لإضافة معالج KSP يعمل أثناء البناء، لكنه لا يُضمَّن في مسار فئات وقت التشغيل؟

مراجعة: دمج KSP في بناء Gradle

أهم النقاط:

طبّق إضافة com.google.devtools.ksp؛ وأضف المعالج باستخدام تبعية ksp()
توجد المصادر المُولَّدة في build/generated/ksp/ وتُضاف تلقائيًا إلى مجموعة المصادر
مرّر الخيارات من Gradle باستخدام ksp { arg() }؛ واقرأها باستخدام environment.options
استخدم Dependencies مع createNewFile() لإجراء عمليات إعادة بناء تزايدية دقيقة
يعمل مع Android (إعدادات حسب نوع البناء) ومع Kotlin Multiplatform

الأسئلة الشائعة

هل درس «دمج معالجات KSP في عملية بناء Gradle» مجاني؟

نعم — نص درس «دمج معالجات KSP في عملية بناء Gradle» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Kotlin Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

ماذا ستتعلم في «دمج معالجات KSP في عملية بناء Gradle»؟

اضبط KSP في Gradle وأضف المصادر المُنشأة وصحّح مخرجات المعالج. تتمرن على Kotlin Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Kotlin Academy؟

لا تُشترط خبرة سابقة. Kotlin Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.

كم من الوقت يستغرق درس «دمج معالجات KSP في عملية بناء Gradle»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Kotlin Academy هذا؟

نعم. كل درس في Kotlin Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

‏KSP مقابل KAPT: لماذا KSP أسرع
كتابة أول SymbolProcessor لك
إنشاء ملفات مصدر Kotlin باستخدام KotlinPoet
دمج معالجات KSP في عملية بناء Gradle

← العودة إلى Kotlin Academy