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

בדף הזה מפורטות הנחיות להוספה ולהגדרה של מעבדי הערות כיחסי תלות בפרויקט. מידע נוסף על מעבדי הערות זמין בקטע הגדרת יחסי תלות.

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

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

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

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

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

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 ומוסיפה הערות לכל ארגומנט של המעבד.

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 עוזרת לשפר את ביצועי ה-build, קראו את המאמר אחסון ב-cache של פרויקטים ב-Java.

השבתת בדיקת השגיאות של מעבד ההערות

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

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

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