Ajouter des options globales

R8 fournit des options globales qui modifient les optimisations de R8 dans l'ensemble de l'application ou affectent chaque règle de conservation. Ces options sont conservées dans le fichier proguard-rules.pro, ainsi que les règles de conservation. Certaines de ces options globales permettent de configurer une optimisation supplémentaire, tandis que d'autres désactivent certains aspects de l'optimisation.

Options globales pour une optimisation supplémentaire

Les options globales suivantes permettent une optimisation supplémentaire :

• -repackageclasses [<optional-package-name>] : reconditionne les classes dans un seul package spécifié pour réduire davantage la taille de l'application. Si vous ne fournissez pas le nom de package facultatif, les classes sont déplacées dans le package vide par défaut. Il s'agit d'un paramètre recommandé pour les applications.
• -allowaccessmodification : permet à R8 de modifier (généralement d'élargir) la visibilité des classes, des champs et des méthodes pour effectuer des optimisations plus poussées. Activé lorsque proguard-android-optimize.txt est utilisé. Depuis le plug-in Android Gradle (AGP) 8.2, il s'agit de la configuration par défaut si vous utilisez R8 en mode complet.

Avertissement : Si vous êtes l'auteur d'une bibliothèque, vous ne devez jamais ajouter d'options globales pour des optimisations supplémentaires dans les règles de conservation des consommateurs. Pour en savoir plus sur l'optimisation des bibliothèques, consultez Optimisation pour les auteurs de bibliothèques.

Voici un exemple de configuration avec une optimisation supplémentaire activée :

-repackageclasses
-allowaccessmodification

Options globales pour limiter l'optimisation

Les options globales suivantes vous permettent de désactiver certains aspects de l'optimisation des applications. Elles sont utiles lorsque vous affinez vos règles de conservation ou que vous activez R8 pour la première fois.

• -dontoptimize : empêche l'optimisation du code, par exemple l'intégration de méthodes. Cette option peut être utilisée pendant le développement, mais pas dans les versions de production.
• -dontshrink : empêche la suppression du code non référencé et les optimisations de code. Cette option peut être utilisée pendant le développement, mais pas dans les versions de production.
• -dontobfuscate : empêche le raccourcissement des noms de classes et de méthodes. Il peut être particulièrement utile de désactiver l'obscurcissement pendant le débogage afin de faciliter la lecture des traces de pile. Cette option peut être utilisée pendant le développement, mais pas dans les versions de production.
• -keepattributes <attributes> : accepte une liste d'attributs séparés par une virgule qui doivent être conservés. Si vous n'utilisez pas le proguard-android-optimize.txt par défaut, R8 supprime tous les attributs, y compris RuntimeVisibleAnnotations et Signature. Toutefois, il peut être utile de conserver ces attributs s'ils sont nécessaires dans des cas comme la réflexion. Pour obtenir la liste des attributs que vous pouvez spécifier, consultez Attributs à conserver.

Avertissement : Vous ne devez utiliser les options -dontoptimize, -dontshrink et -dontobfuscate que temporairement lors du débogage ou du développement. Supprimez ces options dans les versions de production, car elles limitent considérablement l'étendue des optimisations.

Conserver les attributs

Les attributs sont des informations supplémentaires associées à différentes parties de votre code. Les attributs stockent des informations telles que les annotations et les signatures génériques de votre code.

Certaines opérations de réflexion nécessitent de conserver des attributs spécifiques pour être exécutées correctement. Exemple :

• Lorsque vous accédez à la structure de classe interne ou externe à l'aide de getEnclosingMethod() ou getDeclaredClasses(), les attributs EnclosingMethod et InnerClasses sont nécessaires.
• Lorsque vous accédez à des signatures génériques à l'aide de getTypeParameters(), l'attribut Signature est nécessaire.

• Lorsque vous accédez aux annotations à l'aide de getAnnotation(), l'attribut RuntimeVisibleAnnotations est nécessaire.

  Remarque : Lorsque vous travaillez sur une règle de conservation pour une annotation, veillez à conserver l'annotation et les classes auxquelles elle est appliquée.

Attributs généralement obligatoires

Lorsque vous utilisez le fichier ProGuard par défaut (proguard-android-optimize.txt ou proguard-android.txt), le plug-in Android Gradle (AGP) conserve les attributs suivants. Notez que certains de ces attributs nécessitent des versions plus récentes d'AGP :

Attribut	Description
AnnotationDefault	Cet attribut se trouve sur les types d'annotation eux-mêmes et stocke la valeur par défaut d'un élément d'annotation. Remarque : Cet attribut est conservé par défaut depuis AGP 7.1 et ne doit être conservé explicitement que dans les applications utilisant des versions antérieures d'AGP.
EnclosingMethod	Cet attribut est présent dans les classes internes qui ne sont pas des classes locales ni anonymes. Il identifie la méthode ou l'initialiseur qui contient immédiatement la classe.
InnerClasses	Cet attribut enregistre des informations sur les classes imbriquées (classes internes, classes imbriquées statiques, classes locales et classes anonymes) définies dans une autre classe.
LineNumberTable	Cet attribut associe les instructions de bytecode à leurs numéros de ligne correspondants dans le fichier source d'origine. Remarque : Cet attribut est conservé par défaut depuis le plug-in Android Gradle (AGP) 8.6. Il n'a besoin d'être conservé explicitement que dans les applications utilisant des versions antérieures d'AGP.
RuntimeVisibleAnnotations	Cet attribut stocke les annotations visibles au moment de l'exécution par réflexion. En règle générale, si des annotations sont utilisées au moment de l'exécution, il s'agit de la seule annotation des attributs *Annotation dont les applications et les règles de consommateur de bibliothèque ont besoin.
RuntimeVisibleParameterAnnotations	Cet attribut stocke les annotations visibles au moment de l'exécution par réflexion sur les paramètres d'une méthode.
RuntimeVisibleTypeAnnotations	Cet attribut stocke les annotations qui s'appliquent aux utilisations de type plutôt qu'aux déclarations. Cet attribut est visible lors de l'exécution.
Signature	Cet attribut stocke une signature de type plus générique pour les classes, les méthodes et les champs, en particulier lorsqu'ils utilisent des génériques (comme List<String>).
SourceFile	Cet attribut stocke le nom du fichier source (fichier .kt ou .java) à partir duquel une classe a été compilée. Il est principalement utilisé par les débogueurs pour afficher les lignes de code source d'origine lors de l'exécution pas à pas du code Java compilé. Il aide les développeurs à retracer l'exécution jusqu'au code qu'ils ont écrit. Remarque : Cet attribut est conservé par défaut depuis AGP 8.2 et ne doit être conservé explicitement que dans les applications utilisant des versions antérieures d'AGP.

Pour les applications qui utilisent proguard-android-optimize.txt, les règles de conservation définies par AGP sont adéquates dans la plupart des scénarios. Toutefois, si vous écrivez du code pour une bibliothèque, vous devez spécifier tous les attributs requis par votre bibliothèque dans ses règles de conservation des consommateurs, même s'ils sont définis dans cette liste. Cela garantit la robustesse de votre bibliothèque si les développeurs décident de ne pas inclure proguard-android-optimize.txt.

Conseil : Nous vous recommandons de conserver le moins d'attributs possible, car chaque attribut conservé limite l'optimisation globale.

Remarque : Les attributs supplémentaires contenant des informations de débogage (tels que LocalVariableTable et LocalVariableTypeTable) sont contrôlés par le mode de compilation R8 (release ou débogage). Les inclure avec -keepattributes n'a aucun effet.

Attributs de conservation supplémentaires

Vous pouvez spécifier des attributs supplémentaires à conserver, mais ils ne sont pas nécessaires pour la grande majorité des scénarios d'accès par réflexion ou JNI. Toutefois, certains d'entre eux peuvent encore être fréquemment utilisés lors de l'optimisation des bibliothèques.

Attribut	Description
MethodParameters	Cet attribut fournit des informations sur les paramètres d'une méthode, en particulier leurs noms et leurs indicateurs d'accès.
Exceptions	Cet attribut liste les exceptions contrôlées qu'une méthode est déclarée générer.  Cet attribut n'est généralement pas utilisé pour les applications. Pour les auteurs de bibliothèques, elle n'est généralement pas utilisée dans les règles de conservation des consommateurs, mais elle l'est souvent lors de la création de bibliothèques. Pour en savoir plus sur l'optimisation des bibliothèques, consultez Optimisation pour les auteurs de bibliothèques.
RuntimeInvisibleAnnotations	Cet attribut stocke les annotations qui ne sont pas visibles avec la réflexion au moment de l'exécution sur une classe, un champ ou une méthode. Les développeurs d'applications ne doivent pas conserver cet attribut. Pour les auteurs de bibliothèques, cet attribut n'est pas pertinent dans les règles de conservation des consommateurs, mais il est souvent utilisé lors de la création de bibliothèques. Pour en savoir plus sur l'optimisation des bibliothèques, consultez Optimisation pour les auteurs de bibliothèques.
RuntimeInvisibleParameterAnnotations	Cet attribut stocke les annotations qui ne sont pas visibles avec la réflexion au moment de l'exécution sur les paramètres d'une méthode. Les développeurs d'applications ne doivent pas conserver cet attribut. Pour les auteurs de bibliothèques, cet attribut n'est pas pertinent dans les règles de conservation des consommateurs, mais il est souvent utilisé lors de la création de bibliothèques. Pour en savoir plus sur l'optimisation des bibliothèques, consultez Optimisation pour les auteurs de bibliothèques.
RuntimeInvisibleTypeAnnotations	Cet attribut stocke les annotations qui s'appliquent aux utilisations de type plutôt qu'aux déclarations. Cet attribut n'est pas visible au moment de l'exécution. Les développeurs d'applications ne doivent pas conserver cet attribut. Pour les auteurs de bibliothèques, cet attribut n'est pas pertinent dans les règles de conservation des consommateurs, mais il est souvent utilisé lors de la création de bibliothèques. Pour en savoir plus sur l'optimisation des bibliothèques, consultez Optimisation pour les auteurs de bibliothèques.