إضافة معالجات التعليقات التوضيحية

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

في حال إضافة معالجات التعليقات التوضيحية إلى مسار تجميع الفصول الدراسية، ستظهر لك رسالة خطأ مشابهة لما يلي:

Error: Annotation processors must be explicitly declared now.

لحلّ هذا الخطأ، أضِف معالجات التعليقات التوضيحية إلى مشروعك من خلال ضبط موردك باستخدام annotationProcessor كما هو موضّح أدناه:

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly("com.google.dagger:dagger:version-number")
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor("com.google.dagger:dagger-compiler:version-number")
}

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly 'com.google.dagger:dagger:version-number'
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor 'com.google.dagger:dagger-compiler:version-number'
}

ملاحظة: لم يعُد المكوّن الإضافي لنظام Gradle المتوافق مع Android 3.0.0 والإصدارات الأحدث يتوافق مع المكوّن الإضافي android-apt.

تمرير الوسائط إلى معالجات التعليقات التوضيحية

إذا كنت بحاجة إلى تمرير مَعلمات إلى معالج التعليقات التوضيحية، يمكنك إجراء ذلك باستخدام العنصر AnnotationProcessorOptions في إعدادات إنشاء الوحدات. على سبيل المثال، إذا كنت تريد تمرير أنواع البيانات الأساسية كأزواج مفتاح/قيمة، يمكنك استخدام السمة argument، كما هو موضّح أدناه:

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += mapOf("key1" to "value1",
                                   "key2" to "value2")
            }
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument 'key1', 'value1'
                argument 'key2', 'value2'
            }
        }
    }
}

ومع ذلك، عند استخدام الإصدار 3.2.0 من المكوّن الإضافي Android Gradle والإصدارات الأحدث، عليك تمرير مَعلمات المعالج التي تمثّل الملفات أو الأدلة باستخدام واجهة CommandLineArgumentProvider في Gradle.

يتيح لك استخدام CommandLineArgumentProvider أو لمؤلف معالج التعليقات التوضيحية تحسين صحة وأداء الإصدارات التراكمية والنظيفة المخزّنة مؤقتًا من خلال تطبيق تعليقات توضيحية لنوع ملف الإصدار التراكمي على كلّ مَعلمة.

على سبيل المثال، تنفِّذ الفئة أدناه CommandLineArgumentProvider و تضيف تعليقات توضيحية لكلّ مَعلمة للمعالج.

class MyArgsProvider(
    // Annotates each directory as either an input or output for the
    // annotation processor.
    @get:InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
    @get:PathSensitive(PathSensitivity.RELATIVE)
    val inputDir: FileCollection,

    @get:OutputDirectory
    val outputDir: File
) : CommandLineArgumentProvider {
    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.

    override fun asArguments(): Iterable<String> {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
        return listOf("-AinputDir=${inputDir.singleFile.absolutePath}",
                      "-AoutputDir=${outputDir.absolutePath}")
    }
}

android {...}

class MyArgsProvider implements CommandLineArgumentProvider {

    // Annotates each directory as either an input or output for the
    // annotation processor.
    @InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
    @PathSensitive(PathSensitivity.RELATIVE)
    FileCollection inputDir

    @OutputDirectory
    File outputDir

    // The class constructor sets the paths for the input and output directories.
    MyArgsProvider(FileCollection input, File output) {
        inputDir = input
        outputDir = output
    }

    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.
    @Override
    Iterable<String> asArguments() {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
        ["-AinputDir=${inputDir.singleFile.absolutePath}",
         "-AoutputDir=${outputDir.absolutePath}"]
    }
}

android {...}

بعد تحديد فئة تنفِّذ CommandLineArgumentProvider، عليك إنشاء مثيل لها ونقله إلى المكوّن الإضافي لنظام التشغيل Android باستخدام الأسلوب annotationProcessorOptions.compilerArgumentProvider ، كما هو موضّح أدناه.

// This is in your module's build.gradle file.
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
                compilerArgumentProvider(MyArgsProvider(files("input/path"),
                                                          file("output/path")))
            }
        }
    }
}

// This is in your module's build.gradle file.
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
                compilerArgumentProvider new MyArgsProvider(files("input/path"),
                                         new File("output/path"))
            }
        }
    }
}

للاطّلاع على مزيد من المعلومات عن كيفية مساعدة تنفيذ CommandLineArgumentProvider في تحسين أداء عملية الإنشاء، يمكنك قراءة مقالة تخزين مشاريع Java.

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

إذا كانت لديك تبعيات في مسار تجميع الترجمة تتضمّن معالجات annotation لا تحتاج إليها، يمكنك إيقاف فحص الأخطاء عن طريق إضافة العنصر التالي إلى ملف build.gradle.kts. يُرجى العِلم أنّه لم تتم إضافة معالجات التعليقات التوضيحية التي تضيفها إلى مسار تجميع الترجمة إلى مسار معالج الترجمة.

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument("includeCompileClasspath", "false")
            }
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                includeCompileClasspath false
            }
        }
    }
}

في حال استخدام لغة Kotlin وkapt:

android {
    ...
    defaultConfig {
        ...
        kapt {
            includeCompileClasspath = false
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        kapt {
            includeCompileClasspath false
        }
    }
}

إذا واجهت مشاكل بعد نقل معالجات التعليقات التوضيحية في مشروعك إلى مسار تجميع المعالج، يمكنك السماح لمعالجات التعليقات التوضيحية في compile مسار التجميع من خلال ضبط includeCompileClasspath على true. ومع ذلك، لا يُنصح بضبط قيمة هذه السمة على true، وسيتمّ إزالة خيار إجراء ذلك في تحديث مستقبلي للمكوّن الإضافي لنظام التشغيل Android.