À propos des règles de conservation

Lorsque vous activez l'optimisation de l'application avec les paramètres par défaut, R8 effectue des optimisations importantes afin de maximiser les avantages en termes de performances. R8 apporte des modifications importantes au code, y compris en renommant, en déplaçant et en supprimant des classes, des champs et des méthodes. Si vous constatez que ces modifications entraînent des erreurs, vous devez spécifier les parties du code que R8 ne doit pas modifier en les déclarant dans des règles de conservation.

Scénarios courants nécessitant des règles de conservation

R8 identifie et conserve tous les appels directs dans votre code. Toutefois, R8 ne peut pas voir les utilisations indirectes du code, ce qui peut l'amener à supprimer du code dont votre application a besoin, entraînant ainsi des plantages. Utilisez les règles de conservation pour indiquer à R8 de conserver ce code utilisé indirectement. Voici quelques situations courantes dans lesquelles vous aurez probablement besoin de règles de conservation :

  • Code accédé par réflexion : R8 ne peut pas détecter quand des classes, des champs ou des méthodes sont accédés par réflexion. Par exemple, R8 ne peut pas identifier une méthode recherchée par son nom à l'aide de Class.getDeclaredMethod() ni une annotation récupérée avec Class.getAnnotation(). Dans ce cas, R8 peut renommer ou supprimer complètement ces méthodes et annotations, ce qui entraîne une erreur ClassNotFoundException ou NoSuchMethodException au moment de l'exécution.
  • Code appelé à partir de l'interface JNI (Java Native Interface) : lorsqu'un code natif (C ou C++) appelle une méthode Java ou Kotlin, ou qu'un code Java ou Kotlin appelle un code C++ avec JNI, l'appel est basé sur une recherche dynamique de chaîne du nom de la méthode. R8 ne peut pas voir l'appel de méthode dynamique basé sur une chaîne. Ses optimisations peuvent donc casser votre code.

Cette liste de scénarios nécessitant des règles de conservation n'est pas exhaustive, mais elle couvre la plupart des cas où vous pourriez en avoir besoin.

Ajouter des règles de conservation à votre application

La configuration de vos règles de conservation dépend de la version d'AGP que vous utilisez.

Les applications plus volumineuses contiennent généralement du code dans plusieurs modules de bibliothèque. Dans ce cas, il est souvent préférable de placer les règles de conservation à côté du code auquel elles s'appliquent dans le module de bibliothèque spécifique. La différence cruciale si vous conservez des règles de conservation pour les bibliothèques réside dans la façon dont vous déclarez ces règles dans le fichier build.gradle.kts (ou build.gradle) du module de votre bibliothèque. Pour en savoir plus, consultez Optimisation pour les auteurs de bibliothèques.

Pour les versions 9.3 et ultérieures d'AGP

Ajoutez vos règles à un fichier portant le suffixe .keep dans le répertoire src/<variant>/keepRules. Exemple : src/main/keepRules/custom-rules.keep. Notez que l'utilisation du DSL mis à jour pour AGP 9.3 et versions ultérieures permet d'optimiser le code et les ressources, et ne vous demande pas de définir explicitement le fichier de règles Keep Android par défaut (proguard-android-optimize.txt), car il est inclus par défaut, sauf s'il est explicitement omis.

Kotlin

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

Groovy

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

Omettre les règles de conservation par défaut de la plate-forme Android (avancé)

AGP fournit un ensemble de règles de plate-forme Android par défaut. Pour omettre ces règles de la configuration de votre projet et gérer vous-même toutes les règles de conservation, définissez optimization.keepRules.includeDefault sur 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.
                }
            }
        }
    }
}

Ancien DSL pour les versions d'AGP antérieures à 9.3

Ajoutez vos règles à un fichier proguard-rules.pro situé dans le répertoire racine du module d'application. Il est possible que le fichier soit déjà présent. Si ce n'est pas le cas, créez-le. Pour appliquer les règles du fichier, vous devez le déclarer dans votre fichier build.gradle.kts (ou build.gradle) au niveau du module.

Par défaut, votre fichier de compilation inclut également le fichier proguard-android-optimize.txt. Ce fichier inclut les règles requises pour la plupart des projets Android. Vous devez donc le laisser dans le fichier build. Ce fichier est basé sur le fichier proguard-common.txt et partage du contenu avec celui-ci.

Ancien DSL (Kotlin)

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

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

Ancien DSL (Groovy)

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

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

Ajouter une règle de conservation

Lorsque vous ajoutez des règles de conservation, vous pouvez inclure des options globales et définir vos propres règles de conservation.

  • Options globales : les options globales sont des directives générales qui affectent le fonctionnement de R8 sur l'ensemble de votre codebase. Pour en savoir plus, consultez Options globales.

  • Règles de conservation : les règles de conservation doivent être conçues avec soin pour assurer une optimisation maximale du code sans casser involontairement votre application. Pour savoir comment écrire des règles de conservation, consultez Ajouter des règles de conservation.

Règles de conservation pour les auteurs de bibliothèques

Après avoir découvert les options globales et la syntaxe des règles de conservation, consultez Optimisation pour les auteurs de bibliothèques pour en savoir plus.