اضافه کردن پردازنده های حاشیه نویسی

این صفحه شامل راهنمایی دقیق در مورد نحوه افزودن و پیکربندی پردازشگرهای حاشیه نویسی به عنوان وابستگی پروژه است. برای کسب اطلاعات بیشتر در مورد پردازنده های حاشیه نویسی، به ورودی پیکربندی وابستگی ها مراجعه کنید.

اگر پردازنده های حاشیه نویسی را به مسیر کلاس کامپایل خود اضافه کنید، یک پیام خطایی شبیه به زیر خواهید دید:

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

با این حال، هنگام استفاده از پلاگین Android Gradle نسخه 3.2.0 و بالاتر، باید آرگومان‌های پردازنده را ارسال کنید که فایل‌ها یا دایرکتوری‌ها را با استفاده از رابط 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 را پیاده سازی می کند، باید یک نمونه ایجاد کنید و با استفاده از متد 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 به بهبود عملکرد ساخت کمک می کند، پروژه های Caching Java را بخوانید.

بررسی خطای پردازشگر حاشیه نویسی را غیرفعال کنید

اگر وابستگی هایی به مسیر کلاس کامپایل دارید که شامل پردازنده های حاشیه نویسی است که به آنها نیاز ندارید، می توانید با افزودن موارد زیر به فایل 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
        }
    }
}

اگر پس از انتقال پردازنده های حاشیه نویسی پروژه خود به مسیر کلاس پردازنده، با مشکلاتی مواجه شدید، می توانید با تنظیم includeCompileClasspath روی true ، به پردازنده های حاشیه نویسی در مسیر کلاس کامپایل اجازه دهید. با این حال، تنظیم این ویژگی روی true توصیه نمی شود و گزینه انجام این کار در آپدیت بعدی افزونه اندروید حذف خواهد شد.