Sobre as regras de retenção

Ao ativar a otimização de apps com as configurações padrão, o R8 realiza otimizações extensivas para maximizar os benefícios de performance. O R8 faz modificações substanciais no código, incluindo renomear, mover e remover classes, campos e métodos. Se essas modificações causarem erros, especifique quais partes do código o R8 não deve modificar declarando-as nas regras keep.

Cenários comuns que exigem regras keep

O R8 identifica e preserva todas as chamadas diretas no código. No entanto, o R8 não consegue identificar usos indiretos de código, o que pode fazer com que ele remova o código necessário para o app, causando falhas. Use regras keep para informar ao R8 que ele precisa preservar esse código usado indiretamente. Confira algumas situações comuns em que você provavelmente precisará de regras keep:

  • Código acessado por reflexão: o R8 não consegue identificar quando classes, campos ou métodos são acessados com reflexão. Por exemplo, o R8 não consegue identificar um método pesquisado pelo nome usando Class.getDeclaredMethod() ou uma anotação recuperada com Class.getAnnotation(). Nesses casos, o R8 pode renomear esses métodos e anotações ou removê-los completamente, levando a uma ClassNotFoundException ou uma NoSuchMethodException no ambiente de execução.
  • Código chamado da Java Native Interface (JNI): quando o código nativo (C ou C++) chama um método Java ou Kotlin, ou o código Java ou Kotlin chama o código C++ com JNI, a chamada é baseada em uma pesquisa de string dinâmica do nome do método. O R8 não consegue identificar a chamada de método baseada em string dinâmica, e as otimizações podem quebrar o código.

Esta não é uma lista exaustiva de cenários que exigem regras keep, mas ela abrange a maioria dos casos em que você pode precisar de regras keep.

Se o código usar reflexão ou for chamado da JNI, você poderá anotar esse código com as anotações do Jetpack Keep em vez de escrever regras keep manualmente. O plug-in do Gradle gera as regras keep das anotações no momento da criação.

Como adicionar regras keep ao app

A configuração das regras keep depende da versão do AGP que você usa.

Apps maiores geralmente têm código em vários módulos de biblioteca. Nesses casos, geralmente é melhor colocar as regras keep junto com o código a que elas se aplicam no módulo de biblioteca específico. A diferença crucial na manutenção das regras keep para bibliotecas está na forma como você declara essas regras no arquivo do módulo de biblioteca build.gradle.kts (ou build.gradle). Consulte Otimização para autores de bibliotecas para saber mais.

Para versões do AGP 9.3 e mais recentes

Adicione suas regras a um arquivo com o sufixo .keep no src/<variant>/keepRules diretório. Por exemplo, src/main/keepRules/custom-rules.keep. O uso da DSL atualizada para AGP 9.3 e mais recentes permite a otimização de código e recursos e não exige que você defina explicitamente o arquivo de regras keep padrão do Android (proguard-android-optimize.txt), porque ele é incluído por padrão, a menos que seja omitido explicitamente.

Kotlin

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

Omitir as regras keep padrão da plataforma Android (avançado)

O AGP oferece um conjunto de regras padrão da plataforma Android. Para omitir essas regras da configuração do projeto e gerenciar todas as regras keep, defina optimization.keepRules.includeDefault como false.

Kotlin

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

DSL legada para versões do AGP anteriores à 9.3

Adicione suas regras a um arquivo proguard-rules.pro localizado no diretório raiz do módulo do app. O arquivo já pode estar lá, mas, se não estiver, crie-o. Para aplicar as regras no arquivo, declare-o no arquivo do módulo build.gradle.kts (ou build.gradle).

Por padrão, o arquivo de build também inclui o arquivo proguard-android-optimize.txt. Esse arquivo inclui regras necessárias para a maioria dos projetos do Android. Portanto, deixe-o no arquivo de build. Esse arquivo é baseado no arquivo proguard-common.txt e compartilha conteúdo com ele.

DSL legada (Kotlin)

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true

            proguardFiles(
                // Default file with default optimization rules.
                getDefaultProguardFile("proguard-android-optimize.txt"),
                ...
            )
        }
    }
}

DSL legada (Groovy)

android {
    buildTypes {
        release {
            minifyEnabled = true
            shrinkResources = true

            // Default file with default optimization rules.
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
            ...
        }
    }
}

Adicionar uma regra keep

Ao adicionar regras keep, você pode incluir opções globais e definir suas próprias regras keep.

  • Opções globais: são diretivas gerais que afetam a forma como o R8 opera em toda a base de código. Para saber mais, consulte Opções globais.

  • Regras keep: as regras keep precisam ser projetadas com cuidado para garantir o equilíbrio certo entre maximizar a otimização de código sem quebrar o app inadvertidamente. Para saber como escrever regras keep, consulte Adicionar regras keep.

Regras keep para autores de bibliotecas

Depois de aprender sobre as opções globais e a sintaxe das regras keep, consulte Otimização para autores de bibliotecas para mais detalhes.