Atualizações da API do Plug-in do Android para Gradle

Esta página monitora as descontinuações e remoções da API do Plug-in do Android para Gradle (AGP), além de fornecer informações sobre como atualizar seu código adequadamente.

Descontinuação de APIs e monitoramento de remoções

A tabela abaixo resume quando as APIs AGP são descontinuadas e removidas em relação à versão do AGP.

AGP 8.0

Veja a seguir atualizações importantes da API para a AGP 8.0.

A API Transform foi removida

A partir da AGP 8.0, a API Transform foi removida. Isso significa que todas as classes no pacote com.android.build.api.transform foram removidas.

A API Transform está sendo removida para melhorar o desempenho do build. Os projetos que usam a API Transform forçam a AGP a usar um fluxo menos otimizado para o build, podendo resultar em grandes regressões nos tempos de compilação. Também é difícil usar a API Transform e combiná-la com outros recursos do Gradle. O objetivo das APIs de substituição é facilitar a extensão do AGP sem introduzir problemas de precisão de performance ou de criação.

APIs de substituição

Não há uma substituição única para a API Transform. Em vez disso, há novas APIs voltadas para cada caso de uso. Todas as APIs de substituição estão no bloco androidComponents {}. Essas APIs estão disponíveis pela AGP 7.2.

Suporte à transformação de bytecode

Para transformar bytecode, use a API Instrumentation. No caso de bibliotecas, é possível registrar uma instrumentação apenas para classes de projetos locais. Para apps e testes, você pode escolher registrar uma instrumentação apenas para classes locais ou todas as classes, incluindo dependências locais e remotas. Para usar a API, a instrumentação é executada de maneira independente em cada classe, com acesso limitado a outras classes no caminho de classe (consulte createClassVisitor() para ver mais informações). Essa restrição melhora o desempenho de builds completos e incrementais, mantendo a superfície da API simples. Cada biblioteca é instrumentada em paralelo assim que fica pronta, e não depois que toda a compilação é concluída. Além disso, uma mudança em uma única classe significa que apenas as classes afetadas precisam ser reinstrumentadas em um build incremental. Para ver um exemplo de como usar a API Instrumentation, consulte o Como transformar classes com o ASM Roteiro do AGP.

Suporte à adição de classes geradas ao app

Para adicionar outras classes geradas ao app, use a API Artifacts com MultipleArtifact.ALL_CLASSES_DIRS. Especificamente, use

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

com MultipleArtifact.ALL_CLASSES_DIRS para anexar outros diretórios gerados às classes do projeto. A API Artifacts vai selecionar automaticamente um local exclusivo para a saída da tarefa personalizada. Consulte a Roteiro addToAllClasses para conferir um exemplo de como usar essa API.

Suporte a transformações com base na análise completa do programa

Para implementar transformações com base na análise completa do programa, todas as classes podem ser transformadas em uma única tarefa. Essa abordagem precisa ser usada com cuidado, já que tem um custo de performance de build muito maior do que o uso da API Instrumentation. Se o plug-in usar essa API, recomendamos que a transformação seja ativada por tipo de build para que os desenvolvedores de apps possam a desativar em builds de desenvolvimento.

Para registrar uma tarefa que transforma todas as classes ao mesmo tempo, o Plug-in do Android para Gradle 7.4 lançou a API Artifacts.forScope. Para transformar todas as classes do projeto atual, use Artifacts.forScope.PROJECT. Para transformar todas as classes no projeto atual, em projetos importados e em todas as dependências externas, use Artifacts.forScope.ALL. O código abaixo mostra como usar Artifacts.forScope.ALL para registrar uma tarefa que transforma todas as classes ao mesmo tempo:

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

Consulte a Roteiro modificarProjectClasses para obter um exemplo de como usar esta API, e a roteiro personalizávelAgpDsl para ver um exemplo de como registrar extensões personalizadas para os tipos de build do Android.

Se o caso de uso não for coberto por nenhuma das APIs AndroidComponents, informe um bug.

Vários plug-ins usados com frequência já migraram para essas novas APIs, incluindo o plug-in Monitoramento de desempenho do Firebase (1.4.1 é compatível com a AGP 8.0) e o plug-in Hilt Gradle (2.40.1 é compatível com a AGP 8.0). O AGP Upgrade Assistant também vai ajudar os desenvolvedores de projetos a fazer upgrade dos plug-ins mais usados, conforme necessário.

Se você estiver usando a API Transform com um plug-in de terceiros, informe ao autor que o plug-in vai precisar ser atualizado para funcionar com as novas APIs da AGP 8.0.

AGP 7.2

Veja a seguir atualizações importantes da API para a AGP 7.2.

O RenderScript foi descontinuado

A partir da versão 7.2 da AGP, as APIs do RenderScript foram descontinuadas. Elas ainda funcionam, mas vão invocar avisos e ser completamente removidas em versões futuras da AGP. Para saber como fazer a transição para o RenderScript, consulte Migrar do RenderScript.

Component.transformClassesWith e Component.setAsmFramesComputationMode foram descontinuados.

A partir do AGP 7.2, as APIs de instrumentação de bytecode da classe Component.transformClassesWith e Component.setAsmFramesComputationMode foram descontinuadas. Elas foram movidas para um novo bloco, Component.instrumentation, que contém todas as APIs relacionadas à configuração do processo de instrumentação. Para continuar usando esses recursos de instrumentação, use as APIs correspondentes no novo bloco, conforme mostrado no snippet de código a seguir:

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }