Ajouter des processeurs d'annotations

Cette page inclut des instructions détaillées sur l'ajout et la configuration de processeurs d'annotation en tant que dépendances de projet. Pour en savoir plus sur les processeurs d'annotations, consultez la section Configurer les dépendances.

Si vous ajoutez des processeurs d'annotations à votre classpath de compilation, un message d'erreur semblable au suivant s'affiche :

Error: Annotation processors must be explicitly declared now.

Pour résoudre cette erreur, ajoutez des processeurs d'annotations à votre projet en configurant votre dépendance à l'aide de annotationProcessor, comme indiqué ci-dessous :

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

Remarque : Le plug-in Android pour Gradle 3.0.0 et ses versions ultérieures ne sont plus compatibles avec le plug-in android-apt.

Transmettre des arguments aux processeurs d'annotations

Si vous devez transmettre des arguments à un processeur d'annotations, utilisez le bloc AnnotationProcessorOptions dans la configuration de compilation de votre module. Par exemple, si vous souhaitez transmettre des types de données primitifs en tant que paires clé-valeur, vous pouvez utiliser la propriété argument, comme indiqué ci-dessous :

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

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

Toutefois, lorsque vous utilisez le plug-in Android Gradle 3.2.0 ou une version ultérieure, vous devez transmettre les arguments de processeur qui représentent des fichiers ou des répertoires directement à l'aide de l'interface CommandLineArgumentProvider de Gradle.

Utiliser CommandLineArgumentProvider permet (à vous ou à l'auteur du processeur d'annotations) d'améliorer l'exactitude et les performances des compilations propres incrémentielles et mises en cache, en appliquant des annotations de type de propriété de compilation incrémentielle à chaque argument.

Par exemple, la classe ci-dessous implémente CommandLineArgumentProvider et annote chaque argument pour le processeur.

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

Après avoir défini une classe mettant en œuvre CommandLineArgumentProvider, vous devez créer une instance et la transmettre au plug-in Android à l'aide de la méthode annotationProcessorOptions.compilerArgumentProvider, comme indiqué ci-dessous.

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

Pour savoir en quoi la mise en œuvre de CommandLineArgumentProvider permet d'améliorer les performances de compilation, consultez la page Mettre en cache des projets Java.

Désactiver la vérification des erreurs du processeur d'annotations

Si vous avez des dépendances sur le classpath de compilation qui incluent des processeurs d'annotations dont vous n'avez pas besoin, vous pouvez désactiver la vérification des erreurs en ajoutant ce qui suit à votre fichier build.gradle.kts. N'oubliez pas que les processeurs d'annotations que vous ajoutez au classpath de compilation ne sont toujours pas ajoutés au classpath du processeur.

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

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

Si vous utilisez du Kotlin avec kapt :

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

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

Si vous rencontrez des problèmes après avoir migré les processeurs d'annotations de votre projet vers le classpath du processeur, vous pouvez autoriser les processeurs d'annotations sur le classpath de compilation en définissant includeCompileClasspath sur true. Toutefois, définir cette propriété sur true n'est pas recommandé, et cette option sera supprimée lors d'une prochaine mise à jour du plug-in Android.