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.

O R8 também aceita, mas ignora, algumas opções legadas do ProGuard. Para mais informações, consulte Remover opções legadas do ProGuard.

Opções globais para otimização adicional

As seguintes opções globais permitem otimizações adicionais:

  • -repackageclasses [<optional-package-name>]: reempacota classes em um único pacote para reduzir o tamanho do app. Se você não fornecer o nome do pacote opcional, as classes serão movidas para o pacote sem nome (padrão). Essa é a configuração recomendada para apps porque resulta em arquivos DEX menores ao omitir o prefixo do pacote dos nomes de classe. Desde o Plug-in do Android para Gradle (AGP) 9.1, essa é a configuração padrão para apps. Para desativar essa otimização, use -dontrepackage.
  • -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ê ativar a otimização completa com o R8.

  • -processkotlinnullchecks [level]: permite que o R8 mude as verificações de valores nulos do Kotlin Intrinsics para apenas remover a mensagem de erro ou remover completamente a verificação explícita de valores nulos.

    Os valores de level, ordenados do mais fraco ao mais forte, têm o seguinte efeito:

    • keep não muda as verificações.
    • O remove_message reescreve cada chamada de método de verificação para uma chamada de getClass() no primeiro argumento da chamada, mantendo a verificação de nulo, mas sem nenhuma mensagem.
    • remove remove completamente as verificações.

    Por padrão, o R8 usa remove_message. Qualquer especificação de -processkotlinnullchecks substitui isso. Se especificado várias vezes, o valor mais forte será usado.

    O -processkotlinnullchecks é compatível com o AGP 9.0.0.

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 de 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, facilitando a leitura dos rastreamentos de pilha. 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. Observação: 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 em 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 retenção 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 eles 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

É possível 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 durante a otimização de 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.

Esse atributo normalmente não é usado para apps. Para autores de bibliotecas, ele não é usado normalmente 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 do consumidor, 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 tempo 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 do consumidor, 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.

Remover opções legadas do ProGuard

O R8 aceita algumas opções que só tinham efeito no ProGuard, mas as ignora. Essas opções costumam permanecer em configurações migradas do ProGuard ou copiadas de projetos mais antigos. Como eles não afetam a saída do R8, remova-os do arquivo proguard-rules.pro para facilitar a compreensão e a manutenção da configuração.

O R8 ignora as seguintes opções sem mostrar um aviso:

  • -adaptkotlinmetadata
  • -android
  • -dontpreverify
  • -dontskipnonpubliclibraryclasses
  • -dontskipnonpubliclibraryclassmembers
  • -dontusemixedcaseclassnames
  • -forceprocessing
  • -mergeinterfacesaggressively
  • -optimizationpasses
  • -optimizations
  • -overloadaggressively
  • -target
  • -verbose

O R8 ignora as seguintes opções e informa um aviso durante o build:

  • -addconfigurationdebugging (o suporte foi removido no AGP 9.0)
  • -assumenoescapingparameters
  • -assumenoexternalreturnvalues
  • -assumenoexternalsideeffects
  • -dump
  • -useuniqueclassmembernames

O R8 não oferece suporte a -skipnonpubliclibraryclasses e informa um erro se a configuração contiver esse elemento.