KaptExecution في Kotlin: ما يختبئ وراء خطأ Gradle

تعلم Python بسهولة دون إرهاق نظري. حل مهام عملية مع التحقق التلقائي واكتب الكود مباشرة في المتصفح.

مقدمة: لماذا يعطل KaptExecution البناء وكيفية إصلاح ذلك

\n\n

إذا واجهت مرة واحدة على الأقل الخطأ A failure occurred while executing org.jetbrains.kotlin.gradle.internal.KaptExecution، فأنت تعلم كم هو مزعج. يتعطل البناء، ويظهر Gradle نصًا أحمر، وفي السجلات تظهر تتبعات مكدس غير مفهومة. على Stack Overflow، حظي هذا السؤال بآلاف المشاهدات، لكن معظم الإجابات هي مجرد "حاول مسح ذاكرة التخزين المؤقت". سنذهب إلى أبعد من ذلك.

\n\n

في هذه المقالة، لن نقدم حلولًا جاهزة فقط. سننظر تحت الغطاء لآلية Kapt (أداة معالجة التعليقات التوضيحية في Kotlin) ونتحقق مما يحدث بالضبط عندما يقوم Gradle بتشغيل KaptExecution. ستتعلم كيفية عمل توليد الكود، وأين تختبئ الأخطاء النموذجية وكيفية منعها. والأهم من ذلك، ستحصل على أمثلة عملية بلغة Kotlin يمكنك تطبيقها فورًا في مشروعك.

\n\n

هذه مادة تعليمية لـ pythonlib.ru، مُعدة للمطورين الذين لا يريدون فقط نسخ الأوامر، بل فهم ما يحدث داخل أداة البناء.

\n\n

ما هو KaptExecution ولماذا هو مطلوب

\n\n

Kapt هو إضافة (plugin) لـ Kotlin تسمح باستخدام معالجات التعليقات التوضيحية المتوافقة مع Java (مثل Dagger و Room و Glide و Moshi) في مشاريع Kotlin. عندما تكتب تعليقًا توضيحيًا مثل @Inject أو @Entity، يقوم المترجم بتوليد كود إضافي (فئات، مصانع، DAO).

\n\n

داخل Gradle، يعمل Kapt كمهمة منفصلة. عند تشغيل البناء، يستدعي Gradle KaptExecution - وهو أمر يقوم بتشغيل مترجم Kotlin مع تفعيل معالجة التعليقات التوضيحية. إذا حدث خطأ ما في هذه المرحلة (على سبيل المثال، ألقى المعالج استثناءً أو نفدت الذاكرة)، فسترى ذلك الخطأ بعينه.

\n\n

كيف يبدو KaptExecution في Gradle

\n\n

في ملف build.gradle.kts (أو build.gradle)، يتم توصيل Kapt كالتالي:

\n\n

plugins {\n    kotlin("kapt") version "1.9.0"\n}\n\ndependencies {\n    kapt("com.google.dagger:dagger-compiler:2.48")\n}\n

\n\n

عند تشغيل ./gradlew build، يقوم Gradle بإنشاء عملية فرعية Java/Kotlin تنفذ KaptExecution. في هذه اللحظة، يتم تحميل معالجات التعليقات التوضيحية، وتحليل التعليقات التوضيحية، وتوليد الملفات في مجلد build/generated/source/kapt.

\n\n

الأسباب الرئيسية لخطأ KaptExecution

\n\n

يمكن أن يحدث الخطأ بسبب عوامل مختلفة. دعنا نستعرض السيناريوهات الأكثر شيوعًا.

\n\n

1. تعارض إصدارات Kotlin و Kapt

\n\n

Kapt هو جزء من Kotlin Gradle Plugin. إذا كان إصدار الإضافة لا يتطابق مع إصدار Kotlin، فقد يفشل المعالج. على سبيل المثال:

\n\n

// غير صحيح\nplugins {\n    kotlin("jvm") version "1.8.20"\n    kotlin("kapt") version "1.9.0" // تعارض\n}\n

\n\n

الحل: يجب أن تتطابق الإصدارات.

\n\n

2. عدم كفاية الذاكرة لمعالجة التعليقات التوضيحية

\n\n

يقوم KaptExecution بتشغيل عملية JVM منفصلة. إذا كنت تعالج العديد من التعليقات التوضيحية (مثل Room مع عشرات الكيانات)، فقد لا تكفي الذاكرة (heap). في السجلات، سترى OutOfMemoryError.

\n\n

الحل: قم بزيادة الذاكرة لـ Gradle daemon في ملف gradle.properties:

\n\n

org.gradle.jvmargs=-Xmx4g -XX:MaxPermSize=512m\nkapt.use.worker.api=false\n

\n\n

3. أخطاء في معالج التعليقات التوضيحية

\n\n

أحيانًا، يحتوي المعالج نفسه (مثل إصدار قديم من Dagger أو Room) على أخطاء. تظهر فقط مع هياكل كود معينة.

\n\n

مثال: التبعية الدائرية في Dagger قد تسبب StackOverflowError داخل KaptExecution.

\n\n

// مثال على كود إشكالي\n@Module\nclass MyModule {\n    @Provides\n    fun provideA(b: B): A = A(b)\n\n    @Provides\n    fun provideB(a: A): B = B(a) // تبعية دائرية\n}\n

\n\n

سينهار KaptExecution مع رسالة Circular dependency detected. الحل هو إعادة تصميم رسم بياني للتبعيات.