הוספה של מעבדי הערות

בדף הזה מוסבר בפירוט איך להוסיף ולהגדיר מעבדי אנוטציות (Annotation processor) כתלויות בפרויקט. מידע נוסף על מעבדי אנוטציות זמין בערך הגדרת יחסי תלות.

אם תוסיפו מעבדי אנוטציות ל-classpath של הקומפילציה, תופיע הודעת שגיאה דומה לזו:

Error: Annotation processors must be explicitly declared now.

כדי לפתור את השגיאה הזו, צריך להוסיף מעבדי אנוטציות לפרויקט על ידי הגדרת התלות באמצעות annotationProcessor, כמו בדוגמה הבאה:

Kotlin

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'
}

הערה: פלאגין Android ל-Gradle בגרסה 3.0.0 ואילך לא תומך יותר בפלאגין android-apt.

העברת ארגומנטים למעבדי אנוטציות (Annotation processor)

אם אתם צריכים להעביר ארגומנטים למעבד אנוטציות, אתם יכולים לעשות את זה באמצעות הבלוק AnnotationProcessorOptions בתצורת ה-build של המודול. לדוגמה, אם רוצים להעביר סוגי נתונים פרימיטיביים כצמדי מפתח/ערך, אפשר להשתמש במאפיין argument, כמו בדוגמה הבאה:

Kotlin

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

מגניב

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

עם זאת, כשמשתמשים בפלאגין של Android Gradle מגרסה 3.2.0 ואילך, צריך להעביר ארגומנטים של מעבד שמייצגים קבצים או ספריות באמצעות הממשק CommandLineArgumentProvider של Gradle.

השימוש ב-CommandLineArgumentProvider מאפשר לכם או ליוצר של מעבד האנוטציות לשפר את הדיוק והביצועים של גרסאות build מצטברות וגרסאות build נקיות שנשמרו במטמון, על ידי החלת אנוטציות של סוגי מאפיינים של גרסאות build מצטברות על כל ארגומנט.

לדוגמה, המחלקה בדוגמה הבאה מטמיעה את CommandLineArgumentProvider ומוסיפה הערה לכל ארגומנט של המעבד.

הערה: בדרך כלל, מי שיוצר את מעבד האנוטציות מספק את המחלקה הזו או הוראות לכתיבת מחלקה כזו. הסיבה לכך היא שכל ארגומנט צריך לציין את הערת הסוג הנכונה של מאפיין ה-build כדי לפעול כמצופה.

Kotlin

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 באמצעות ה-method‏ annotationProcessorOptions.compilerArgumentProvider, כמו בדוגמה הבאה.

Kotlin

// 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"))
            }
        }
    }
}

במאמר שמירת פרויקטים ב-Java במטמון מוסבר איך הטמעת CommandLineArgumentProvider עוזרת לשפר את ביצועי ה-build.

השבתת בדיקת השגיאות של מעבד האנוטציות (Annotation processor)

אם יש לכם תלויות ב-classpath של ה-compile שכוללות מעבדי אנוטציות שאתם לא צריכים, אתם יכולים להשבית את בדיקת השגיאות על ידי הוספת הקוד הבא לקובץ build.gradle.kts. חשוב לזכור שמעבדי האנוטציות שמוסיפים ל-classpath של הקומפילציה עדיין לא מתווספים ל-classpath של המעבד.

Kotlin

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

מגניב

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

אם אתם משתמשים ב-Kotlin וב-kapt:

Kotlin

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

מגניב

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

אם נתקלתם בבעיות אחרי שהעברתם את מעבדי האנוטציות של הפרויקט ל-classpath של המעבד, אתם יכולים לאפשר מעבדי אנוטציות ב-classpath של הקומפיילר על ידי הגדרת includeCompileClasspath ל-true. עם זאת, לא מומלץ להגדיר את המאפיין הזה לערך true, והאפשרות לעשות זאת תוסר בעדכון עתידי של הפלאגין של Android.