Aggiungere opzioni globali

R8 fornisce opzioni globali che modificano le ottimizzazioni di R8 in tutta l'app o influiscono su ogni regola di conservazione. Queste opzioni vengono gestite nel file proguard-rules.pro, insieme alle regole di conservazione. Alcune di queste opzioni globali configurano un'ottimizzazione aggiuntiva, mentre altre disattivano determinati aspetti dell'ottimizzazione.

Opzioni globali per l'ottimizzazione aggiuntiva

Le seguenti opzioni globali consentono un'ulteriore ottimizzazione:

• -repackageclasses [<optional-package-name>]: ricompone le classi in un unico pacchetto specificato per ridurre ulteriormente le dimensioni dell'app. Se non fornisci il nome del pacchetto facoltativo, le classi vengono spostate nel pacchetto vuoto predefinito. Si tratta di un'impostazione consigliata per le app.
• -allowaccessmodification: consente a R8 di modificare (in genere ampliare) la visibilità di classi, campi e metodi per eseguire ottimizzazioni più estese. Attivato quando viene utilizzato proguard-android-optimize.txt. A partire dal plug-in Android per Gradle (AGP) 8.2, questa è la configurazione predefinita se utilizzi R8 in modalità completa.

Avviso: se sei l'autore di una libreria, non devi mai aggiungere nessuna delle opzioni globali per ottimizzazioni aggiuntive nelle regole di conservazione dei consumatori. Per ulteriori dettagli sull'ottimizzazione delle librerie, consulta Ottimizzazione per gli autori di librerie.

Di seguito è riportato un esempio di configurazione con l'ottimizzazione aggiuntiva attivata:

-repackageclasses
-allowaccessmodification

Opzioni globali per limitare l'ottimizzazione

Le seguenti opzioni globali ti consentono di disattivare determinati aspetti dell'ottimizzazione delle app e sono utili quando perfezioni le regole di conservazione o attivi R8 per la prima volta.

• -dontoptimize: impedisce l'ottimizzazione del codice, ad esempio l'incorporamento del metodo. Questa opzione può essere utilizzata durante lo sviluppo, ma non deve essere utilizzata nelle build di produzione.
• -dontshrink: impedisce la rimozione del codice non referenziato e le ottimizzazioni del codice. Questa opzione può essere utilizzata durante lo sviluppo, ma non deve essere utilizzata nelle build di produzione.
• -dontobfuscate: Impedisce l'abbreviazione dei nomi di classi e metodi. Può essere particolarmente utile disattivare l'offuscamento durante il debug in modo che le tracce dello stack siano più facili da leggere. Questa opzione può essere utilizzata durante lo sviluppo, ma non deve essere utilizzata nelle build di produzione.
• -keepattributes <attributes>: accetta un elenco separato da virgole di attributi che devono essere conservati. Se non utilizzi proguard-android-optimize.txt predefinito, R8 rimuove tutti gli attributi, inclusi RuntimeVisibleAnnotations e Signature. Tuttavia, può essere utile conservare questi attributi se sono necessari in casi come la reflection. Per un elenco degli attributi che puoi specificare, vedi Mantieni attributi.

Avviso: devi utilizzare le opzioni -dontoptimize, -dontshrink e -dontobfuscate temporaneamente durante il debug o lo sviluppo. Rimuovi queste opzioni nelle build di produzione, in quanto limitano notevolmente l'entità delle ottimizzazioni.

Mantieni gli attributi

Gli attributi sono informazioni aggiuntive associate a diverse parti del tuo codice. Gli attributi archiviano informazioni come annotazioni e firme generiche del codice.

Alcune operazioni di reflection richiedono che vengano conservati attributi specifici per l'esecuzione corretta. Ad esempio:

• Quando accedi alla struttura della classe interna o esterna utilizzando getEnclosingMethod() o getDeclaredClasses(), sono necessari gli attributi EnclosingMethod e InnerClasses.
• Quando accedi alle firme generiche utilizzando getTypeParameters(), è necessario l'attributo Signature.

• Quando accedi alle annotazioni utilizzando getAnnotation(), è necessario l'attributo RuntimeVisibleAnnotations.

  Nota: quando lavori a una regola di conservazione per un'annotazione, assicurati di conservare l'annotazione e le classi a cui viene applicata.

Attributi richiesti di frequente

Quando utilizzi il file Proguard predefinito (proguard-android-optimize.txt o proguard-android.txt), il plug-in Android per Gradle (AGP) conserva i seguenti attributi. Tieni presente che alcuni di questi attributi richiedono versioni più recenti di AGP:

Attributo	Descrizione
AnnotationDefault	Questo attributo si trova nei tipi di annotazione stessi e memorizza il valore predefinito per un elemento di annotazione. Nota:questo attributo viene mantenuto per impostazione predefinita a partire da AGP 7.1 e deve essere mantenuto esplicitamente solo nelle app che utilizzano versioni precedenti di AGP.
EnclosingMethod	Questo attributo è presente nelle classi interne che non sono classi locali o anonime. Identifica il metodo o l'inizializzatore che contiene immediatamente la classe.
InnerClasses	Questo attributo registra informazioni sulle classi nidificate (classi interne, classi nidificate statiche, classi locali e classi anonime) definite all'interno di un'altra classe.
LineNumberTable	Questo attributo mappa le istruzioni bytecode ai numeri di riga corrispondenti nel file sorgente originale. Nota: questo attributo viene mantenuto per impostazione predefinita a partire da Android Gradle Plugin (AGP) 8.6 e deve essere mantenuto esplicitamente solo nelle app che utilizzano versioni precedenti di AGP.
RuntimeVisibleAnnotations	Questo attributo memorizza le annotazioni visibili in fase di runtime tramite reflection. In genere, se le annotazioni vengono utilizzate in fase di runtime, questa è l'unica annotazione degli attributi *Annotation necessaria alle app e nelle regole di consumo delle librerie.
RuntimeVisibleParameterAnnotations	Questo attributo memorizza le annotazioni visibili in fase di runtime tramite reflection sui parametri di un metodo.
RuntimeVisibleTypeAnnotations	Questo attributo memorizza le annotazioni che si applicano agli utilizzi dei tipi anziché solo alle dichiarazioni. Questo attributo è visibile in fase di runtime.
Signature	Questo attributo memorizza una firma di tipo più generica per classi, metodi e campi, in particolare quando utilizzano i generici (come List<String>).
SourceFile	Questo attributo memorizza il nome del file di origine (file .kt o .java) da cui è stata compilata una classe. Viene utilizzato principalmente dai debugger per visualizzare le righe del codice sorgente originale durante l'esecuzione passo passo del codice Java compilato. Aiuta gli sviluppatori a tracciare l'esecuzione fino al codice scritto. Nota:questo attributo viene mantenuto per impostazione predefinita a partire da AGP 8.2 e deve essere mantenuto esplicitamente solo nelle app che utilizzano versioni precedenti di AGP.

Per le app che utilizzano proguard-android-optimize.txt, le regole di conservazione definite da AGP sono adeguate nella maggior parte degli scenari. Tuttavia, se stai scrivendo codice per una libreria, devi specificare tutti gli attributi richiesti dalla libreria nelle relative regole di conservazione per i consumatori, anche se sono definiti in questo elenco. In questo modo, la tua libreria è solida se gli sviluppatori decidono di non includere proguard-android-optimize.txt.

Suggerimento:ti consigliamo di conservare il minor numero possibile di attributi, perché ogni attributo che conservi limita un'ottimizzazione globale.

Nota:gli attributi aggiuntivi con informazioni di debug (ad esempio LocalVariableTable e LocalVariableTypeTable) sono controllati in base alla modalità di rilascio o debug della build R8. Includerli con -keepattributes non ha alcun effetto.

Attributi di conservazione aggiuntivi

Puoi specificare attributi aggiuntivi da conservare, ma non sono necessari per la stragrande maggioranza degli scenari di accesso JNI o basati sulla reflection. Tuttavia, alcune di queste potrebbero essere ancora utilizzate di frequente durante l'ottimizzazione delle librerie.

Attributo	Descrizione
MethodParameters	Questo attributo fornisce informazioni sui parametri di un metodo, in particolare i relativi nomi e flag di accesso.
Exceptions	Questo attributo elenca le eccezioni controllate che un metodo è dichiarato di generare. Questo attributo non viene in genere utilizzato per le app. Per gli autori di librerie, non viene in genere utilizzata nelle regole di conservazione dei consumatori, ma spesso viene utilizzata durante la creazione di librerie. Per informazioni dettagliate sull'ottimizzazione delle librerie, consulta Ottimizzazione per gli autori di librerie.
RuntimeInvisibleAnnotations	Questo attributo memorizza le annotazioni che non sono visibili con la reflection in fase di runtime su una classe, un campo o un metodo. Gli sviluppatori di app non devono conservare questo attributo. Per gli autori di librerie, questo attributo non è pertinente nelle regole di conservazione dei consumatori, ma viene spesso utilizzato durante la creazione di librerie. Per informazioni dettagliate sull'ottimizzazione delle librerie, consulta Ottimizzazione per gli autori di librerie.
RuntimeInvisibleParameterAnnotations	Questo attributo memorizza le annotazioni che non sono visibili con la reflection in fase di runtime sui parametri di un metodo. Gli sviluppatori di app non devono conservare questo attributo. Per gli autori di librerie, questo attributo non è pertinente nelle regole di conservazione dei consumatori, ma viene spesso utilizzato durante la creazione di librerie. Per informazioni dettagliate sull'ottimizzazione delle librerie, consulta Ottimizzazione per gli autori di librerie.
RuntimeInvisibleTypeAnnotations	Questo attributo memorizza le annotazioni che si applicano agli utilizzi dei tipi anziché solo alle dichiarazioni. Questo attributo non è visibile in fase di runtime. Gli sviluppatori di app non devono conservare questo attributo. Per gli autori di librerie, questo attributo non è pertinente nelle regole di conservazione dei consumatori, ma viene spesso utilizzato durante la creazione di librerie. Per informazioni dettagliate sull'ottimizzazione delle librerie, consulta Ottimizzazione per gli autori di librerie.