Optimierung für Bibliotheksautoren

Als Bibliotheksautor müssen Sie dafür sorgen, dass App-Entwickler Ihre Bibliothek einfach in ihre App einbinden können, ohne dass die Qualität der Nutzererfahrung beeinträchtigt wird. Das bedeutet, dass Ihre Bibliothek mit der Android-Optimierung (R8) kompatibel sein muss, ohne dass der Entwickler zusätzliche Schritte ausführen muss. Alternativ müssen Sie dokumentieren, dass die Bibliothek möglicherweise nicht für die Verwendung unter Android geeignet ist. Es ist wichtig, dass Bibliotheken, die für die Verwendung unter Android vorgesehen sind, wichtige App-Optimierungen nicht verhindern und zusätzliche Optimierungsanforderungen erfüllen.

Diese Dokumentation richtet sich an Entwickler veröffentlichter Bibliotheken, kann aber auch für Entwickler interner Bibliotheksmodule in einer großen, modularisierten App nützlich sein.

Wenn Sie App-Entwickler sind und mehr über die Optimierung Ihrer Android-App erfahren möchten, lesen Sie den Hilfeartikel App-Optimierung aktivieren. Informationen dazu, welche Bibliotheken sich für die Verwendung eignen, finden Sie unter Bibliotheken sorgfältig auswählen.

Arten von Behaltensregeln

Es gibt zwei verschiedene Arten von Behaltensregeln, die Sie in Bibliotheken verwenden können:

  • In den Aufbewahrungsregeln für Nutzer müssen Regeln angegeben werden, die alles aufbewahren, was die Bibliothek reflektiert. Wenn eine Bibliothek Reflection oder JNI verwendet, um ihren Code oder den von einer Client-App definierten Code aufzurufen, müssen diese Regeln beschreiben, welcher Code beibehalten werden muss. Bibliotheken sollten Beibehaltungsregeln für Nutzer enthalten, die dasselbe Format wie Beibehaltungsregeln für Apps haben. Diese Regeln sind in Bibliotheksartefakten (AARs oder JARs) gebündelt und werden bei der Optimierung von Android-Apps automatisch verwendet, wenn die Bibliothek verwendet wird. Diese Regeln werden in der Datei verwaltet, die mit dem Attribut consumerProguardFiles in Ihrer build.gradle.kts-Datei (oder build.gradle-Datei) angegeben ist. Weitere Informationen finden Sie unter Aufbewahrungsregeln für Nutzer schreiben.
  • Aufbewahrungsregeln für die Erstellung von Bibliotheken werden angewendet, wenn Ihre Bibliothek erstellt wird. Sie sind nur erforderlich, wenn Sie Ihre Bibliothek während des Builds teilweise optimieren möchten. Sie müssen verhindern, dass die öffentliche API der Bibliothek entfernt wird. Andernfalls ist die öffentliche API nicht in der Bibliotheksdistribution vorhanden, was bedeutet, dass App-Entwickler die Bibliothek nicht verwenden können. Diese Regeln werden in der Datei verwaltet, die mit dem Attribut proguardFiles in Ihrer build.gradle.kts-Datei (oder build.gradle-Datei) angegeben ist. Weitere Informationen finden Sie unter AAR-Bibliotheks-Build optimieren.

Anforderungen und Richtlinien für die Optimierung

Die R8-Konfiguration in Bibliotheken hat globale Auswirkungen auf die endgültige Binärgröße und Leistung der nutzenden App. Abgesehen von den allgemeinen Best Practices für Beibehaltungsregeln müssen Bibliotheksautoren bestimmte Anforderungen erfüllen und zusätzliche Richtlinien beachten.

Optimierungsanforderungen erfüllen

Ineffiziente Bibliotheken sind ein Hauptgrund für aufgeblähte Apps, verschwendeten Arbeitsspeicher, langsame Starts und ANR-Fehler („App antwortet nicht“). Bibliotheken dürfen nicht gegen die folgenden Anforderungen verstoßen, um die App-Qualität und die Nutzerfreundlichkeit nicht erheblich zu beeinträchtigen.

  • Keine allgemeinen oder paketweiten Beibehaltungsregeln: Ihre Bibliothek darf keine allgemeinen Beibehaltungsregeln enthalten, die den Großteil des Codes in Ihrer Bibliothek oder in einer anderen Bibliothek beibehalten. Allgemeine Beibehaltungsregeln können Abstürze kurzfristig beheben, erhöhen aber die App-Größe aller Apps, die deine Bibliothek verwenden.

    Fügen Sie keine paketweiten Beibehaltungsregeln (z. B. -keep class com.mylibrary.** {*; }) für Pakete in Ihrer Bibliothek oder anderen referenzierten Bibliotheken hinzu. Solche Regeln schränken die Optimierung für diese Pakete in allen Apps ein, die Ihre Bibliothek verwenden.

    Fügen Sie keine allgemeinen Beibehaltungsregeln für Abhängigkeiten von Drittanbietern ein, die Ihre Bibliothek verwendet (z. B. -keep public class com.google.android.gms.** { *; }). Viele externe Bibliotheken enthalten bereits eigene Beibehaltungsregeln für Nutzer. Wenn Sie eine paketweite Regel einführen, werden diese Regeln ersetzt und R8 wird gezwungen, nicht referenzierten Abhängigkeitscode in der gesamten Anwendung beizubehalten.

  • Keine unangemessenen globalen Regeln: Verwenden Sie niemals globale Optionen wie -dontobfuscate oder -allowaccessmodification.

  • Verwendung von Codegenerierung statt Reflexion, wenn möglich: Verwenden Sie nach Möglichkeit die Codegenerierung (codegen) statt Reflexion. Codegenerierung und Reflexion sind gängige Ansätze, um Boilerplate-Code beim Programmieren zu vermeiden. Die Codegenerierung ist jedoch besser mit einem App-Optimierer wie R8 kompatibel.

    Bei der Codegenerierung wird der Code während des Build-Prozesses analysiert und geändert. Da nach der Kompilierung keine größeren Änderungen mehr vorgenommen werden, weiß der Optimierer, welcher Code letztendlich benötigt wird und was sicher entfernt werden kann.

    Bei der Reflexion wird Code zur Laufzeit analysiert und manipuliert. Da der Code erst bei der Ausführung endgültig festgelegt wird, weiß der Optimierer nicht, welcher Code sicher entfernt werden kann. Wahrscheinlich wird Code entfernt, der während der Laufzeit dynamisch über Reflexion verwendet wird, was zu App-Abstürzen bei Nutzern führt.

    Viele moderne Bibliotheken verwenden Codegenerierung anstelle von Reflection. Unter KSP finden Sie einen gängigen Einstiegspunkt, der von Room, Hilt und vielen anderen verwendet wird.

  • Unterstützung des vollständigen R8-Modus: Ihre Bibliothek sollte nicht abstürzen, wenn der vollständige R8-Modus aktiviert ist. Der vollständige Modus von R8 ist der empfohlene Modus für die Verwendung von R8 und ist seit AGP 8.0, das 2023 stabilisiert wurde, der Standardmodus. Wenn Ihre Bibliothek unter R8 abstürzt, besteht die Lösung darin, den spezifischen Reflexions- oder JNI-Einstiegspunkt zu identifizieren und eine gezielte Regel hinzuzufügen, anstatt das gesamte Paket beizubehalten. Verwenden Sie Jetpack Keep, um gezielte Regeln aus Annotationen an diesen Einstiegspunkten zu generieren.

Weitere Empfehlungen

Zusätzlich zu den Optimierungsanforderungen gibt es die folgenden Empfehlungen.

  • Verwenden Sie -repackageclasses nicht in der Datei mit den Beibehaltungsregeln für Nutzer Ihrer Bibliothek. Die Keep-Regeln für Nutzer werden in die R8-Konfiguration jeder App zusammengeführt, die deine Bibliothek verwendet. Diese globale Option gilt also für die gesamte App und überschreibt die eigenen Einstellungen des App-Entwicklers für das Repackaging. Ab AGP 9.0 schlägt die Veröffentlichung einer Bibliothek standardmäßig fehl, wenn die Beibehaltungsregeln für Nutzer globale Optionen enthalten. Weitere Informationen finden Sie in den Versionshinweisen zu AGP 9.0.

    Wenn Sie den Build Ihrer Bibliothek optimieren möchten, können Sie stattdessen -repackageclasses mit einem internen Paketnamen wie <your.library.package>.internal in der Keep-Regeldatei des Builds Ihrer Bibliothek verwenden. Dies kann die Effizienz Ihrer Bibliothek in nicht optimierten Apps verbessern, ist aber im Allgemeinen nicht erforderlich, da Apps ebenfalls optimiert werden sollten.

  • Deklarieren Sie alle Attribute, die für die Funktion Ihrer Bibliothek erforderlich sind, in den Keep-Regeldateien Ihrer Bibliothek, auch wenn es Überschneidungen mit den in proguard-android-optimize.txt definierten Attributen gibt.

  • Wenn Sie die folgenden Attribute in Ihrer Bibliotheksdistribution benötigen, behalten Sie sie in der Build-Keep-Regeldatei Ihrer Bibliothek bei und nicht in der Consumer-Keep-Regeldatei Ihrer Bibliothek:

    • AnnotationDefault
    • EnclosingMethod
    • Exceptions
    • InnerClasses
    • RuntimeInvisibleAnnotations
    • RuntimeInvisibleParameterAnnotations
    • RuntimeInvisibleTypeAnnotations
    • RuntimeVisibleAnnotations
    • RuntimeVisibleParameterAnnotations
    • RuntimeVisibleTypeAnnotations
    • Signature
  • Bibliotheksautoren sollten das Attribut RuntimeVisibleAnnotations in ihren Consumer-Keep-Regeln beibehalten, wenn Annotationen zur Laufzeit verwendet werden.

  • Bibliotheksautoren sollten die folgenden globalen Optionen nicht in ihren Beibehaltungsregeln für Nutzer verwenden. Wie -repackageclasses konfigurieren diese Optionen den gesamten R8-Build der App und nicht nur den Code Ihrer Bibliothek. Überlassen Sie sie daher dem App-Entwickler:

    • -include
    • -basedirectory
    • -injars
    • -outjars
    • -libraryjars
    • -repackageclasses
    • -flattenpackagehierarchy
    • -allowaccessmodification
    • -renamesourcefileattribute
    • -ignorewarnings
    • -addconfigurationdebugging
    • -printconfiguration
    • -printmapping
    • -printusage
    • -printseeds
    • -applymapping
    • -obfuscationdictionary
    • -classobfuscationdictionary
    • -packageobfuscationdictionary

Wann Reflexion in Ordnung ist

Wenn Sie die Reflexion verwenden müssen, sollten Sie nur in eine der folgenden Optionen reflektieren:

  • Spezifische Zieltypen (spezifische Schnittstellenimplementierer oder Unterklassen)
  • Code mit einer bestimmten Laufzeitanmerkung

Die Verwendung von Reflexion auf diese Weise begrenzt die Laufzeitkosten und ermöglicht das Schreiben von zielgerichteten Beibehaltungsregeln für Nutzer.

Diese spezifische und gezielte Form der Reflexion ist ein Muster, das sowohl im Android-Framework (z. B. beim Aufblähen von Aktivitäten, Ansichten und Drawables) als auch in AndroidX-Bibliotheken (z. B. beim Erstellen von WorkManager ListenableWorkers oder RoomDatabases) zu finden ist. Im Gegensatz dazu ist die offene Reflexion von Gson nicht für die Verwendung in Android-Apps geeignet.

Häufige Missverständnisse

Einige häufige Missverständnisse können dazu führen, dass Sie R8 falsch konfigurieren. Dazu gehören:

  • Falsches Verständnis der Optimierungen von R8: Entgegen der landläufigen Meinung beschränken sich die Optimierungen von R8 nicht nur auf die Verschleierung, sondern umfassen auch die Codekomprimierung und logische Optimierungen mit Methoden-Inlining und Klassenzusammenführungstechniken. Weitere Informationen finden Sie unter R8-Optimierung – Übersicht.

  • Optimierung von verschleierten Bibliotheken umgehen: Ein häufiger Fehler besteht darin, eine Bibliothek von der Optimierung auszuschließen, weil sie beim Kompilieren in ein AAR (Android-Archiv) oder JAR (Java-Archiv) optimiert oder verschleiert wurde. Die Optimierungen während der Erstellung der Bibliothek sind begrenzt. Ihre App sollte die Optimierung der Bibliothek nicht deaktivieren, indem sie in eine Keep-Regel aufgenommen wird. Weitere Informationen finden Sie unter AAR-Bibliotheks-Build optimieren.

  • Falsches Verständnis der Option -keep: Die Regel -keep verhindert, dass R8 Optimierungsdurchläufe ausführt. Weitere Informationen finden Sie unter Richtige Aufbewahrungsoption auswählen.

Qualität der Aufbewahrungsregel für Nutzer prüfen

Wenn Sie prüfen möchten, ob Ihre Bibliothek die Codeoptimierung nicht zu stark einschränkt, wenn sie in eine App eingebettet ist, verwenden Sie ein Bibliotheksbeispiel oder eine Integrationstest-App. Aktivieren Sie R8 und prüfen Sie die allgemeine Qualität der R8-Konfiguration der App mit dem R8 Configuration Analyzer.

Wenn Ihre Consumer-Regeln die Optimierung großer Teile des Codes Ihrer Bibliothek einschränken, müssen sie verfeinert werden. Schränken Sie die Consumer-Regeln ein und testen Sie alle betroffenen Aspekte Ihrer Bibliothek in einer App mit aktiviertem R8.

Regelpaket konfigurieren

Damit Ihre Consumer-Keep-Regeln korrekt angewendet werden, müssen Sie sie je nach Bibliotheksformat entsprechend verpacken.

Wenn Sie Jetpack Keep verwenden, um die Reflexions- und JNI-Nutzung Ihrer Bibliothek zu deklarieren, kann das Gradle-Plug-in die generierten Regeln als Consumer-Keep-Regeln für Sie verpacken.

AAR-Bibliotheken

Wenn Sie Nutzerregeln für eine AAR-Bibliothek hinzufügen möchten, verwenden Sie die Option consumerProguardFiles im Build-Skript des Android-Bibliotheksmoduls. Weitere Informationen findest du in unserem Leitfaden zum Erstellen von Bibliotheksmodulen.

Kotlin

android {
    defaultConfig {
        consumerProguardFiles("consumer-proguard-rules.pro")
    }
    ...
}

Groovy

android {
    defaultConfig {
        consumerProguardFiles 'consumer-proguard-rules.pro'
    }
    ...
}

JAR-Bibliotheken

Wenn Sie Regeln mit Ihrer Kotlin- oder Java-Bibliothek bündeln möchten, die als JAR-Datei bereitgestellt wird, legen Sie die Regeldatei mit einem beliebigen Dateinamen im Verzeichnis META-INF/proguard/ der endgültigen JAR-Datei ab. Wenn sich Ihr Code beispielsweise in <libraryroot>/src/main/kotlin befindet, legen Sie eine Nutzerregeldatei unter <libraryroot>/src/main/resources/META-INF/proguard/consumer-proguard-rules.pro ab. Die Regeln werden dann am richtigen Speicherort in Ihrer Ausgabe-JAR gebündelt.

Prüfen Sie, ob die Regeln im endgültigen JAR-Bundle korrekt sind. Dazu müssen sich die Regeln im Verzeichnis META-INF/proguard befinden.

AAR-Bibliotheks-Build optimieren (erweitert)

Im Allgemeinen ist es nicht erforderlich, einen Bibliotheks-Build direkt zu optimieren, da die möglichen Optimierungen beim Erstellen der Bibliothek sehr begrenzt sind. Als Bibliotheksentwickler müssen Sie mehrere Optimierungsphasen berücksichtigen und das Verhalten sowohl bei der Erstellung der Bibliothek als auch der App beibehalten, bevor Sie die Bibliothek optimieren.

Wenn Sie Ihre Bibliothek dennoch beim Erstellen optimieren möchten, wird dies vom Android-Gradle-Plug-in unterstützt.

Kotlin

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        configureEach {
            consumerProguardFiles("consumer-rules.pro")
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles
                getDefaultProguardFile('proguard-android-optimize.txt'),
                'proguard-rules.pro'
        }
        configureEach {
            consumerProguardFiles "consumer-rules.pro"
        }
    }
}

Beachten Sie, dass sich das Verhalten von proguardFiles stark von consumerProguardFiles unterscheidet:

  • proguardFiles werden beim Erstellen verwendet, oft zusammen mit getDefaultProguardFile("proguard-android-optimize.txt"), um zu definieren, welcher Teil Ihrer Bibliothek beim Erstellen der Bibliothek beibehalten werden soll. Das ist mindestens Ihre öffentliche API.
  • consumerProguardFiles hingegen werden in die Bibliothek gepackt, um zu beeinflussen, welche Optimierungen später beim Erstellen einer App, die Ihre Bibliothek verwendet, vorgenommen werden.

Wenn Ihre Bibliothek beispielsweise Reflexion verwendet, um interne Klassen zu erstellen, müssen Sie die Keep-Regeln möglicherweise sowohl in proguardFiles als auch in consumerProguardFiles definieren.

Wenn Sie -repackageclasses im Build Ihrer Bibliothek verwenden, verpacken Sie die Klassen in ein Unterpaket innerhalb des Pakets Ihrer Bibliothek. Verwenden Sie z. B. -repackageclasses 'com.example.mylibrary.internal' statt -repackageclasses 'internal'.

Verschiedene R8-Versionen unterstützen (erweitert)

Sie können Regeln auf bestimmte Versionen von R8 ausrichten. So kann Ihre Bibliothek in Projekten, die neuere R8-Versionen verwenden, optimal funktionieren, während vorhandene Regeln weiterhin in Projekten mit älteren R8-Versionen verwendet werden können.

Wenn Sie gezielte R8-Regeln angeben möchten, müssen Sie sie im Verzeichnis META-INF/com.android.tools innerhalb von classes.jar einer AAR oder im Verzeichnis META-INF/com.android.tools einer JAR einfügen.

In an AAR library:
    proguard.txt (legacy location, the file name must be "proguard.txt")
    classes.jar
    └── META-INF
        └── com.android.tools (location of targeted R8 rules)
            ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
            └── ... (more directories with the same name format)

In a JAR library:
    META-INF
    ├── proguard/<ProGuard-rule-files> (legacy location)
    └── com.android.tools (location of targeted R8 rules)
        ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
        └── ... (more directories with the same name format)

Im Verzeichnis META-INF/com.android.tools können mehrere Unterverzeichnisse mit Namen im Format r8-from-<X>-upto-<Y> vorhanden sein, die angeben, für welche R8-Versionen die Regeln geschrieben wurden. Jedes Unterverzeichnis kann eine oder mehrere Dateien mit den R8-Regeln enthalten, mit beliebigen Dateinamen und Erweiterungen.

Die Teile -from-<X> und -upto-<Y> sind optional, die Version <Y> ist exklusiv und die Versionsbereiche sind in der Regel kontinuierlich, können sich aber auch überschneiden.

Beispiel: r8, r8-upto-8.0.0, r8-from-8.0.0-upto-8.2.0 und r8-from-8.2.0 sind Verzeichnisnamen, die eine Reihe von gezielten R8-Regeln darstellen. Die Regeln im Verzeichnis r8 können von allen R8-Versionen verwendet werden. Die Regeln im Verzeichnis r8-from-8.0.0-upto-8.2.0 können von R8 ab Version 8.0.0 bis einschließlich Version 8.2.0 verwendet werden.

Das Android-Gradle-Plug-in verwendet diese Informationen, um alle Regeln auszuwählen, die von der aktuellen R8-Version verwendet werden können. Wenn in einer Bibliothek keine zielgerichteten R8-Regeln angegeben sind, wählt das Android-Gradle-Plug-in die Regeln aus den Legacy-Speicherorten aus (proguard.txt für ein AAR oder META-INF/proguard/<ProGuard-rule-files> für ein JAR).