Adicionar opções globais

O R8 oferece opções globais que modificam as otimizações do R8 em todo o app ou afetam todas as regras de manutenção. Essas opções são mantidas no arquivo proguard-rules.pro, junto com as regras de retenção. Algumas dessas opções globais configuram otimizações adicionais, enquanto outras desativam determinados aspectos da otimização.

Opções globais para otimização adicional

As seguintes opções globais ativam uma otimização adicional:

  • -repackageclasses [<optional-package-name>]: reempacota classes em um único pacote especificado para reduzir ainda mais o tamanho do app. Se você não fornecer o nome do pacote opcional, as classes serão movidas para o pacote padrão vazio. Essa é uma configuração recomendada para apps.
  • -allowaccessmodification: permite que o R8 mude (normalmente amplie) a visibilidade de classes, campos e métodos para realizar otimizações mais extensas. Ativado quando proguard-android-optimize.txt é usado. Desde o Plug-in do Android para Gradle (AGP) 8.2, essa é a configuração padrão se você usa o R8 no modo completo.

Confira a seguir um exemplo de configuração com otimização adicional ativada:

-repackageclasses
-allowaccessmodification

Opções globais para limitar a otimização

As opções globais a seguir permitem desativar determinados aspectos da otimização de apps e são úteis quando você está refinando as regras de manutenção ou ativando o R8 pela primeira vez.

  • -dontoptimize: impede a otimização do código, por exemplo, a inclusão de métodos. Essa opção pode ser usada durante o desenvolvimento, mas não em builds de produção.
  • -dontshrink: impede a remoção de código não referenciado e otimizações de código. Essa opção pode ser usada durante o desenvolvimento, mas não em builds de produção.
  • -dontobfuscate: impede o encurtamento dos nomes de classes e métodos. Isso pode ser especialmente útil para desativar a ofuscação durante a depuração para que os rastreamentos de pilha sejam mais fáceis de ler. Essa opção pode ser usada durante o desenvolvimento, mas não deve ser usada em builds de produção.
  • -keepattributes <attributes>: aceita uma lista separada por vírgulas de atributos que precisam ser preservados. Se você não estiver usando o proguard-android-optimize.txt padrão, o R8 vai remover todos os atributos, incluindo RuntimeVisibleAnnotations e Signature. No entanto, pode ser útil preservar esses atributos se eles forem necessários em casos como reflexão. Para ver uma lista de atributos que podem ser especificados, consulte Manter atributos.

Manter atributos

Os atributos são informações extras anexadas a diferentes partes do seu código. Os atributos armazenam informações como anotações e assinaturas genéricas do seu código.

Algumas operações reflexivas exigem que atributos específicos sejam mantidos para execução bem-sucedida. Exemplo:

  • Ao acessar a estrutura de classe interna ou externa usando getEnclosingMethod() ou getDeclaredClasses(), os atributos EnclosingMethod e InnerClasses são necessários.
  • Ao acessar assinaturas genéricas usando getTypeParameters(), o atributo Signature é necessário.

  • Ao acessar anotações usando getAnnotation(), o atributo RuntimeVisibleAnnotations é necessário.

Atributos obrigatórios comuns

Ao usar o arquivo ProGuard padrão (proguard-android-optimize.txt ou proguard-android.txt), o Plug-in do Android para Gradle (AGP) mantém os seguintes atributos. Alguns desses atributos exigem versões mais recentes do AGP:

Atributo Descrição
AnnotationDefault Esse atributo é encontrado nos próprios tipos de anotação e armazena o valor padrão de um elemento de anotação.

Observação:esse atributo é mantido por padrão desde o AGP 7.1 e só precisa ser mantido explicitamente em apps que usam versões anteriores do AGP.
EnclosingMethod Esse atributo está presente em classes internas que não são locais ou anônimas. Ele identifica o método ou inicializador que contém imediatamente a classe.
InnerClasses Esse atributo registra informações sobre classes aninhadas (classes internas, classes aninhadas estáticas, classes locais e classes anônimas) definidas em outra classe.
LineNumberTable Esse atributo mapeia instruções de bytecode para os números de linha correspondentes no arquivo de origem original.

Observação:esse atributo é mantido por padrão desde o Plug-in do Android para Gradle (AGP) 8.6 e só precisa ser mantido explicitamente em apps que usam versões anteriores do AGP.
RuntimeVisibleAnnotations Esse atributo armazena anotações visíveis no tempo de execução por reflexão.

Normalmente, se as anotações forem usadas durante a execução, essa será a única anotação dos atributos *Annotation necessária para apps e em regras de consumidores de biblioteca.
RuntimeVisibleParameterAnnotations Esse atributo armazena anotações visíveis no tempo de execução por reflexão nos parâmetros de um método.
RuntimeVisibleTypeAnnotations Esse atributo armazena anotações que se aplicam a usos de tipos, e não apenas a declarações. Esse atributo fica visível no ambiente de execução.
Signature Esse atributo armazena uma assinatura de tipo mais genérica para classes, métodos e campos, principalmente quando eles usam tipos genéricos (como List<String>).
SourceFile Esse atributo armazena o nome do arquivo de origem (arquivo .kt ou .java) de onde uma classe foi compilada. Ele é usado principalmente por depuradores para mostrar as linhas de código-fonte originais ao percorrer o código Java compilado. Ele ajuda os desenvolvedores a rastrear a execução até o código escrito.

Observação:esse atributo é mantido por padrão desde o AGP 8.2 e só precisa ser mantido explicitamente em apps que usam versões anteriores do AGP.

Para apps que usam proguard-android-optimize.txt, as regras de permanência definidas pelo AGP são adequadas na maioria dos cenários. No entanto, se você estiver escrevendo código para uma biblioteca, especifique todos os atributos exigidos por ela nas regras de preservação do consumidor, mesmo que estejam definidos nesta lista. Isso garante que sua biblioteca seja robusta se os desenvolvedores decidirem não incluir proguard-android-optimize.txt.

Outros atributos de retenção

Você pode especificar outros atributos a serem mantidos, mas eles não são necessários para a grande maioria dos cenários de acesso reflexivo ou JNI. No entanto, algumas delas ainda podem ser usadas com frequência ao otimizar bibliotecas.

Atributo Descrição
MethodParameters Esse atributo fornece informações sobre os parâmetros de um método, especificamente os nomes e as flags de acesso.
Exceptions Esse atributo lista as exceções verificadas que um método é declarado para gerar.

Normalmente, esse atributo não é usado para apps. Para autores de bibliotecas, ele não é usado em regras de manutenção do consumidor, mas é usado com frequência ao criar bibliotecas. Para detalhes sobre como otimizar bibliotecas, consulte Otimização para autores de bibliotecas.
RuntimeInvisibleAnnotations Esse atributo armazena anotações que não são visíveis com reflexão em tempo de execução em uma classe, um campo ou um método.

Os desenvolvedores de apps não devem manter esse atributo. Para autores de bibliotecas, esse atributo não é relevante em regras de manutenção de consumidores, mas é usado com frequência ao criar bibliotecas. Para detalhes sobre como otimizar bibliotecas, consulte Otimização para autores de bibliotecas.
RuntimeInvisibleParameterAnnotations Esse atributo armazena anotações que não são visíveis com reflexão no ambiente de execução nos parâmetros de um método.

Os desenvolvedores de apps não devem manter esse atributo. Para autores de bibliotecas, esse atributo não é relevante em regras de manutenção de consumidores, mas é usado com frequência ao criar bibliotecas. Para detalhes sobre como otimizar bibliotecas, consulte Otimização para autores de bibliotecas.
RuntimeInvisibleTypeAnnotations Esse atributo armazena anotações que se aplicam a usos de tipos, e não apenas a declarações. Esse atributo não fica visível durante a execução.

Os desenvolvedores de apps não devem manter esse atributo. Para autores de bibliotecas, esse atributo não é relevante em regras de manutenção de consumidores, mas é usado com frequência ao criar bibliotecas. Para detalhes sobre como otimizar bibliotecas, consulte Otimização para autores de bibliotecas.