Informazioni sulle regole di conservazione

Quando attivi l'ottimizzazione delle app con le impostazioni predefinite, R8 esegue ottimizzazioni estese per massimizzare i vantaggi in termini di prestazioni. R8 apporta modifiche sostanziali al codice, tra cui la ridenominazione, lo spostamento e la rimozione di classi, campi e metodi. Se noti che queste modifiche causano errori, devi specificare quali parti del codice R8 non deve modificare dichiarandole nelle regole di conservazione.

Scenari comuni che richiedono regole di conservazione

R8 identifica e conserva tutte le chiamate dirette nel codice. Tuttavia, R8 non può vedere gli utilizzi indiretti del codice, il che può causare la rimozione di codice necessario alla tua app, provocando arresti anomali. Utilizza le regole keep per indicare a R8 di conservare il codice utilizzato indirettamente. Di seguito sono riportate alcune situazioni comuni in cui è probabile che tu abbia bisogno di regole di conservazione:

• Codice a cui si accede tramite reflection: R8 non riesce a identificare quando si accede a classi, campi o metodi tramite reflection. Ad esempio, R8 non può identificare un metodo cercato per nome utilizzando Class.getDeclaredMethod() o un'annotazione recuperata con Class.getAnnotation(). In questi casi, R8 potrebbe rinominare questi metodi e annotazioni o rimuoverli completamente, causando un ClassNotFoundException o un NoSuchMethodException in fase di runtime.
• Codice chiamato da Java Native Interface (JNI): quando il codice nativo (C o C++) chiama un metodo Java o Kotlin oppure il codice Java o Kotlin chiama il codice C++ con JNI, la chiamata si basa su una ricerca dinamica della stringa del nome del metodo. R8 non riesce a vedere la chiamata al metodo dinamico basato su stringhe, quindi le sue ottimizzazioni potrebbero interrompere il codice.

Questo non è un elenco esaustivo degli scenari che richiedono regole di conservazione, ma questi scenari coprono la maggior parte dei casi in cui potresti aver bisogno di regole di conservazione.

Come aggiungere regole di conservazione all'app

La configurazione delle regole di conservazione dipende dalla versione di AGP che utilizzi.

Le app più grandi in genere hanno codice in più moduli della libreria. In questi casi, è spesso meglio inserire le regole di conservazione insieme al codice a cui si applicano all'interno del modulo della libreria specifico. La differenza fondamentale nel mantenimento delle regole di conservazione per le librerie risiede nel modo in cui vengono dichiarate queste regole all'interno del file build.gradle.kts (o build.gradle) del modulo della libreria. Per saperne di più, consulta la sezione Ottimizzazione per gli autori delle librerie.

Per le versioni di AGP 9.3 e successive

Aggiungi le regole a un file con il suffisso .keep nella directory src/<variant>/keepRules. Ad esempio src/main/keepRules/custom-rules.keep. Tieni presente che l'utilizzo del DSL aggiornato per AGP 9.3 e versioni successive consente l'ottimizzazione del codice e delle risorse e non richiede di definire esplicitamente il file delle regole di conservazione Android predefinito (proguard-android-optimize.txt), perché è incluso per impostazione predefinita, a meno che non venga omesso esplicitamente.

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

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

Omettere le regole di conservazione predefinite della piattaforma Android (avanzate)

AGP fornisce un insieme di regole predefinite della piattaforma Android. Per omettere queste regole dalla configurazione del tuo progetto e gestire autonomamente tutte le regole di conservazione, imposta optimization.keepRules.includeDefault su false.

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.
                }
            }
        }
    }
}

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 precedente per le versioni di AGP precedenti alla 9.3

Aggiungi le regole a un file proguard-rules.pro che si trova nella directory root del modulo dell'app. Il file potrebbe essere già presente, ma se non lo è, crealo. Per applicare le regole nel file, devi dichiarare il file nel file build.gradle.kts (o build.gradle) a livello di modulo.

Per impostazione predefinita, il file di build include anche il file proguard-android-optimize.txt. Questo file include regole necessarie per la maggior parte dei progetti Android, quindi ti consigliamo di lasciarlo nel file di build. Questo file si basa sul file proguard-common.txt e ne condivide i contenuti.

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

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

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

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

Aggiungere una regola di conservazione

Quando aggiungi regole di conservazione, puoi includere opzioni globali e definire le tue regole di conservazione.

• Opzioni globali: le opzioni globali sono direttive generali che influiscono sul funzionamento di R8 sull'intero codebase. Per saperne di più, consulta Opzioni globali.

• Regole di conservazione: le regole di conservazione devono essere progettate con attenzione per assicurarti di ottenere il giusto equilibrio tra la massimizzazione dell'ottimizzazione del codice senza interrompere inavvertitamente la tua app. Per scoprire come scrivere regole di conservazione, consulta Aggiungere regole di conservazione.

Mantieni le regole per gli autori delle librerie

Dopo aver esaminato le opzioni globali e la sintassi per le regole di conservazione, consulta Ottimizzazione per gli autori di librerie per ulteriori dettagli.