Ajouter des processeurs d'annotations

Cette page contient des conseils détaillés sur l'ajout et la configuration d'annotations en tant que dépendances du projet. Pour en savoir plus sur les processeurs d'annotations, voir l'entrée dans Configurez 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 :

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

Groovy

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 :

Kotlin

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

Groovy

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.

L'utilisation de CommandLineArgumentProvider vous permet, d'un processeur d'annotations pour améliorer l'exactitude et les performances les builds propres incrémentiels et mis en cache en appliquant le type de propriété de compilation incrémentielle. des annotations à chaque argument.

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

Remarque : Généralement, les auteurs de processeurs d'annotations fournissent cette classe ou des instructions sur la façon d'écrire une telle classe. En effet, chaque argument doit spécifier la bonne annotation de type de propriété de compilation pour fonctionner comme prévu.

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

Groovy

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.

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

Groovy

// 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.

Kotlin

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

Groovy

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

Si vous utilisez du Kotlin avec kapt :

Kotlin

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

Groovy

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.