Adicionar processadores de anotações

Esta página inclui orientações detalhadas sobre como adicionar e configurar processadores de anotações como dependências do projeto. Para saber mais sobre processadores de anotações, consulte a entrada em Configurar dependências.

Se você adicionar processadores de anotações ao caminho de classe da compilação, vai receber uma mensagem de erro parecida com esta:

Error: Annotation processors must be explicitly declared now.

Para resolver esse erro, adicione processadores de anotações ao seu projeto, configurando sua dependência com annotationProcessor, conforme mostrado abaixo.

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

Observação: o plug-in do Android para Gradle 3.0.0 e versões mais recentes não oferece mais suporte ao plug-in android-apt.

Transmitir argumentos a processadores de anotações

Se você precisar transmitir os argumentos para um processador de anotações, use o bloco AnnotationProcessorOptions na configuração do build do seu módulo. Por exemplo, para transmitir tipos de dados primitivos como pares chave-valor, você pode usar a propriedade argument, conforme mostrado abaixo.

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

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

No entanto, ao usar o plug-in do Android para Gradle 3.2.0 e versões mais recentes, você precisa transmitir argumentos de processador que representam arquivos ou diretórios usando a interface CommandLineArgumentProvider do Gradle.

O uso de CommandLineArgumentProvider permite que você ou o autor do processador de anotações melhore a exatidão e o desempenho de builds limpos incrementais e em cache aplicando anotações de tipo de propriedade de build incremental a cada argumento.

Por exemplo, a classe abaixo implementa CommandLineArgumentProvider e anota cada argumento do processador.

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

Depois de definir uma classe que implementa CommandLineArgumentProvider, você precisa criar uma instância e transmiti-la ao plug-in do Android usando o método annotationProcessorOptions.compilerArgumentProvider, mostrado abaixo.

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

Para saber mais sobre como a implementação de CommandLineArgumentProvider ajuda a melhorar o desempenho do build, leia Projetos Java em cache.

Desativar a verificação de erros do processador de anotações

Se você tiver dependências no caminho de classe da compilação que incluem processadores de anotações desnecessários, poderá desativar a verificação de erros adicionando o seguinte código ao arquivo build.gradle.kts. Não esqueça que os processadores de anotações adicionados ao caminho de classe da compilação ainda não estão incluídos no caminho de classe do processador.

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

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

Se você usa o Kotlin e o kapt (em inglês):

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

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

Se você tiver problemas após migrar os processadores de anotações do seu projeto para o caminho de classe do processador, permita processadores de anotações no caminho de classe da compilação configurando includeCompileClasspath como true. No entanto, configurar essa propriedade como true não é recomendado, e a opção para isso será removida em uma atualização futura do plug-in do Android.