Dodawanie opcji globalnych

R8 udostępnia opcje globalne, które modyfikują optymalizacje R8 w całej aplikacji lub wpływają na każdą regułę zachowywania. Te opcje są przechowywane w pliku proguard-rules.pro wraz z regułami przechowywania. Niektóre z tych opcji globalnych konfigurują dodatkową optymalizację, a inne wyłączają pewne aspekty optymalizacji.

Opcje globalne dotyczące dodatkowej optymalizacji

Te opcje globalne umożliwiają dodatkową optymalizację:

• -repackageclasses [<optional-package-name>]: przekształca klasy w jeden określony pakiet, aby jeszcze bardziej zmniejszyć rozmiar aplikacji. Jeśli nie podasz opcjonalnej nazwy pakietu, klasy zostaną przeniesione do pustego pakietu domyślnego. Jest to zalecane ustawienie w przypadku aplikacji.
• -allowaccessmodification: umożliwia R8 zmianę (zwykle poszerzenie) widoczności klas, pól i metod w celu przeprowadzenia bardziej zaawansowanych optymalizacji. Włączone, gdy używana jest właściwość proguard-android-optimize.txt. Od wersji 8.2 wtyczki Androida do obsługi Gradle (AGP) jest to domyślna konfiguracja, jeśli używasz R8 w trybie pełnym.

Ostrzeżenie: jeśli jesteś autorem biblioteki, nigdy nie dodawaj żadnych globalnych opcji dodatkowych optymalizacji w regułach przechowywania konsumentów. Więcej informacji o optymalizacji bibliotek znajdziesz w artykule Optymalizacja dla autorów bibliotek.

Oto przykład konfiguracji z włączoną dodatkową optymalizacją:

-repackageclasses
-allowaccessmodification

Opcje globalne ograniczające optymalizację

Poniższe opcje globalne umożliwiają wyłączenie niektórych aspektów optymalizacji aplikacji. Są one przydatne, gdy dopracowujesz reguły zachowywania lub po raz pierwszy włączasz R8.

• -dontoptimize: Zapobiega optymalizacji kodu, np. wstawianiu metod. Tej opcji można używać podczas programowania, ale nie należy jej stosować w wersjach produkcyjnych.
• -dontshrink: zapobiega usuwaniu nieużywanego kodu i optymalizacji kodu. Tej opcji można używać podczas programowania, ale nie należy jej stosować w wersjach produkcyjnych.
• -dontobfuscate: zapobiega skracaniu nazw klas i metod. Wyłączenie zaciemniania może być szczególnie przydatne podczas debugowania, ponieważ ułatwia odczytywanie śladów stosu. Tej opcji można używać podczas programowania, ale nie należy jej stosować w wersjach produkcyjnych.
• -keepattributes <attributes>: akceptuje oddzieloną przecinkami listę atrybutów, które mają zostać zachowane. Jeśli nie używasz domyślnego parametru proguard-android-optimize.txt, R8 usuwa wszystkie atrybuty, w tym RuntimeVisibleAnnotations i Signature. Zachowanie tych atrybutów może być jednak przydatne w przypadkach takich jak odbicie. Listę atrybutów, które możesz określić, znajdziesz w sekcji Zachowaj atrybuty.

Ostrzeżenie: opcji -dontoptimize, -dontshrink i -dontobfuscate należy używać tymczasowo podczas debugowania lub tworzenia. Usuń te opcje w wersjach produkcyjnych, ponieważ znacznie ograniczają one zakres optymalizacji.

Zachowaj atrybuty

Atrybuty to dodatkowe informacje dołączone do różnych części kodu. Atrybuty przechowują informacje takie jak adnotacje i ogólne sygnatury z kodu.

Niektóre operacje odblaskowe wymagają zachowania określonych atrybutów, aby można było je pomyślnie wykonać. Na przykład:

• Podczas uzyskiwania dostępu do struktury klasy wewnętrznej lub zewnętrznej za pomocą poleceń getEnclosingMethod() lub getDeclaredClasses() wymagane są atrybuty EnclosingMethod i InnerClasses.
• Aby uzyskać dostęp do podpisów ogólnych za pomocą getTypeParameters(), musisz użyć atrybutu Signature.

• Aby uzyskać dostęp do adnotacji za pomocą getAnnotation(), musisz użyć atrybutu RuntimeVisibleAnnotations.

  Uwaga: podczas tworzenia reguły zachowywania adnotacji pamiętaj, aby zachować adnotację i klasy, do których jest ona stosowana.

Często wymagane atrybuty

Jeśli używasz domyślnego pliku Proguard (proguard-android-optimize.txt lub proguard-android.txt), wtyczka Androida do obsługi Gradle (AGP) zachowuje te atrybuty: Pamiętaj, że niektóre z tych atrybutów wymagają nowszych wersji AGP:

Atrybut	Opis
AnnotationDefault	Ten atrybut znajduje się w samych typach adnotacji i przechowuje wartość domyślną elementu adnotacji. Uwaga: ten atrybut jest domyślnie zachowywany od AGP 7.1 i musi być jawnie zachowywany tylko w aplikacjach korzystających ze starszych wersji AGP.
EnclosingMethod	Ten atrybut występuje w klasach wewnętrznych, które nie są klasami lokalnymi ani anonimowymi. Wskazuje metodę lub inicjator, który bezpośrednio zawiera klasę.
InnerClasses	Ten atrybut rejestruje informacje o zagnieżdżonych klasach (klasach wewnętrznych, statycznych klasach zagnieżdżonych, klasach lokalnych i klasach anonimowych) zdefiniowanych w innej klasie.
LineNumberTable	Ten atrybut mapuje instrukcje kodu bajtowego na odpowiednie numery wierszy w oryginalnym pliku źródłowym. Uwaga: ten atrybut jest domyślnie zachowywany od wersji 8.6 wtyczki Android Gradle Plugin (AGP) i musi być jawnie zachowywany tylko w aplikacjach korzystających z wcześniejszych wersji AGP.
RuntimeVisibleAnnotations	Ten atrybut przechowuje adnotacje, które są widoczne w czasie wykonywania przez odbicie. Zwykle, jeśli adnotacje są używane w czasie działania, jest to jedyna adnotacja z atrybutów *Annotation, która jest potrzebna aplikacjom i regułom konsumentów biblioteki.
RuntimeVisibleParameterAnnotations	Ten atrybut przechowuje adnotacje, które są widoczne w czasie wykonywania przez odbicie na parametrach metody.
RuntimeVisibleTypeAnnotations	Ten atrybut przechowuje adnotacje, które mają zastosowanie do użycia typu, a nie tylko do deklaracji. Ten atrybut jest widoczny w czasie działania programu.
Signature	Ten atrybut przechowuje bardziej ogólny podpis typu dla klas, metod i pól, zwłaszcza gdy używają one typów generycznych (np. List<String>).
SourceFile	Ten atrybut przechowuje nazwę pliku źródłowego (pliku .kt lub .java), z którego skompilowano klasę. Jest on używany głównie przez debugery do wyświetlania oryginalnych wierszy kodu źródłowego podczas przechodzenia przez skompilowany kod Java. Ułatwia to programistom śledzenie wykonania kodu aż do napisanego przez nich kodu. Uwaga: ten atrybut jest domyślnie zachowywany od wersji AGP 8.2. Musi być jawnie zachowywany tylko w aplikacjach korzystających ze starszych wersji AGP.

W przypadku aplikacji, które korzystają z proguard-android-optimize.txt, reguły przechowywania zdefiniowane przez AGP są w większości przypadków wystarczające. Jeśli jednak piszesz kod biblioteki, w jej regułach zachowywania danych użytkowników musisz określić wszystkie atrybuty wymagane przez bibliotekę, nawet jeśli są one zdefiniowane na tej liście. Dzięki temu biblioteka będzie solidna, nawet jeśli programiści zdecydują się nie uwzględniać proguard-android-optimize.txt.

Wskazówka: zalecamy zachowanie jak najmniejszej liczby atrybutów, ponieważ każdy z nich ogranicza optymalizację globalną.

Uwaga: dodatkowe atrybuty z informacjami do debugowania (np. LocalVariableTable i LocalVariableTypeTable) są kontrolowane przez to, czy kompilacja R8 jest w trybie wydania czy debugowania – uwzględnianie ich w -keepattributes nie ma wpływu.

Dodatkowe atrybuty zachowania

Możesz określić dodatkowe atrybuty do zachowania, ale w większości przypadków związanych z odzwierciedleniem lub dostępem JNI nie są one potrzebne. Niektóre z nich mogą być jednak nadal często używane podczas optymalizacji bibliotek.

Atrybut	Opis
MethodParameters	Ten atrybut zawiera informacje o parametrach metody, a w szczególności ich nazwy i flagi dostępu.
Exceptions	Ten atrybut zawiera listę sprawdzonych wyjątków, które metoda zgłasza.  Ten atrybut nie jest zwykle używany w przypadku aplikacji. Autorzy bibliotek zwykle nie używają go w regułach przechowywania dla konsumentów, ale często korzystają z niego podczas tworzenia bibliotek. Więcej informacji o optymalizacji bibliotek znajdziesz w artykule Optymalizacja dla autorów bibliotek.
RuntimeInvisibleAnnotations	Ten atrybut przechowuje adnotacje, które nie są widoczne w czasie działania w przypadku klasy, pola lub metody. Deweloperzy aplikacji nie powinni zachowywać tego atrybutu. W przypadku autorów bibliotek ten atrybut nie ma znaczenia w regułach przechowywania konsumentów, ale jest często używany podczas tworzenia bibliotek. Więcej informacji o optymalizacji bibliotek znajdziesz w artykule Optymalizacja dla autorów bibliotek.
RuntimeInvisibleParameterAnnotations	Ten atrybut przechowuje adnotacje, które nie są widoczne w czasie wykonywania w przypadku odbicia w parametrach metody. Deweloperzy aplikacji nie powinni zachowywać tego atrybutu. W przypadku autorów bibliotek ten atrybut nie ma znaczenia w regułach przechowywania konsumentów, ale jest często używany podczas tworzenia bibliotek. Więcej informacji o optymalizacji bibliotek znajdziesz w artykule Optymalizacja dla autorów bibliotek.
RuntimeInvisibleTypeAnnotations	Ten atrybut przechowuje adnotacje, które mają zastosowanie do użycia typu, a nie tylko do deklaracji. Ten atrybut nie jest widoczny w czasie działania. Deweloperzy aplikacji nie powinni zachowywać tego atrybutu. W przypadku autorów bibliotek ten atrybut nie ma znaczenia w regułach przechowywania konsumentów, ale jest często używany podczas tworzenia bibliotek. Więcej informacji o optymalizacji bibliotek znajdziesz w artykule Optymalizacja dla autorów bibliotek.