Generieren des Baseline-Profils konfigurieren

Das Baseline Profile Gradle-Plug-in erleichtert das Generieren und Verwalten von Baseline Profiles. Er hilft Ihnen bei den folgenden Aufgaben:

• Neue Baseline-Profile für Ihre App erstellen
• Neue Baseline-Profile für Ihre Bibliothek erstellen
• Generierung des Baseline-Profils anpassen

Auf dieser Seite wird erläutert, wie Sie das Baseline Profile Gradle-Plug-in verwenden, um die Generierung Ihrer Baseline-Profile anzupassen.

Plug‑in-Anforderungen

• AGP 8.0 oder höher
• Abhängigkeit von der neuesten Gradle-Plug-in-Version

Von Gradle verwaltete Geräte zum Generieren von Baseline-Profilen verwenden

Wenn Sie ein von Gradle verwaltetes Gerät (Gradle Managed Device, GMD) verwenden möchten, um Ihr Baseline Profile zu generieren, fügen Sie eines in der build.gradle.kts-Konfiguration des Profilerstellungsmoduls hinzu, wahrscheinlich im :baselineprofile-Testmodul, wie im folgenden Beispiel gezeigt:

android {
   testOptions.managedDevices.devices {
       create<com.android.build.api.dsl.ManagedVirtualDevice>("pixel6Api31") {
           device = "Pixel 6"
           apiLevel = 31
           systemImageSource = "aosp"
       }
   }
}

android {
   testOptions.managedDevices.devices {
       pixel6Api31(ManagedVirtualDevice) {
           device 'Pixel 6'
           apiLevel = 31
           systemImageSource 'aosp'
       }
   }
}

Verwenden Sie das GMD, um Baseline-Profile zu generieren. Fügen Sie es dazu der Gradle-Plug-in-Konfiguration für Baseline-Profile im build.gradle.kts des Testmoduls :baselineprofile hinzu:

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

Wenn Sie ein GMD verwenden, um Baseline-Profile zu generieren, legen Sie useConnectedDevices in Ihrem :baselineprofile-Testmodul auf false fest:

baselineProfile {
    ...
    useConnectedDevices = false
}

baselineProfile {
    ...
    useConnectedDevices false
}

Baseline-Profile für verschiedene Varianten erstellen

Sie können Baseline-Profile pro Variante, pro Flavor oder als einzelne Datei generieren, die für alle Varianten verwendet werden kann. Sie können dieses Verhalten über die Zusammenführungseinstellung steuern, wie im folgenden Beispiel im build.gradle.kts des Anwendungs- oder Bibliotheksmoduls gezeigt.

baselineProfile {
    mergeIntoMain = true
}

baselineProfile {
    mergeIntoMain true
}

Wenn Sie die generierten Profile für alle Varianten in einem einzigen Profil zusammenführen möchten, legen Sie mergeIntoMain auf true fest. Wenn diese Einstellung true ist, können keine Baseline-Profile pro Variante generiert werden. Es gibt dann nur eine Gradle-Aufgabe namens generateBaselineProfile. Das Profil wird unter src/main/generated/baselineProfiles ausgegeben.

Wenn Sie das Zusammenführen deaktivieren und ein Profil pro Variante haben möchten, legen Sie mergeIntoMain auf false fest. In diesem Fall sind mehrere variantenspezifische Gradle-Aufgaben vorhanden. Wenn es beispielsweise zwei Varianten gibt, z. B. kostenlos und kostenpflichtig, und einen Release-Buildtyp, sind die Aufgaben die folgenden:

* `generateFreeReleaseBaselineProfile`
* `generatePaidReleaseBaselineProfile`
* `generateReleaseBaselineProfile`

Verwenden Sie den folgenden Code, um das Zusammenführungsverhalten für jede Variante anzugeben:

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain = true
        }
    }
}

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

Im vorherigen Beispiel werden alle Varianten, für die das Flag auf true gesetzt ist, in src/main/generated/baselineProfiles zusammengeführt, während die Profile für die Varianten, für die das Flag auf false gesetzt ist, im Ordner src/<variant>/generated/baselineProfiles beibehalten werden.

Standardmäßig ist mergeIntoMain für Bibliotheken auf true und für Apps auf false festgelegt.

Baseline-Profile beim Zusammenstellen einer neuen Version automatisch generieren

Sie können Baseline-Profile so konfigurieren, dass sie mit jedem Release-Build automatisch generiert werden, anstatt die Aufgabe generateBaselineProfile manuell zu verwenden. Bei der automatischen Generierung wird das aktuellste Profil in den Release-Build aufgenommen.

Verwenden Sie das Flag automaticGenerationDuringBuild, um die automatische Generierung für Release-Builds zu aktivieren:

baselineProfile {
    automaticGenerationDuringBuild = true
}

baselineProfile {
    automaticGenerationDuringBuild true
}

Wenn Sie das automaticGenerationDuringBuild-Flag auf true setzen, wird für jede Release-Assembly ein neues Baseline-Profil generiert. Wenn Sie also eine Aufgabe zum Erstellen eines Release-Builds ausführen, z. B. ./gradlew:app:assembleRelease, wird auch :app:generateReleaseBaselineProfile ausgelöst, die Instrumentierungstests für das Baseline-Profil werden gestartet und der Build für das Baseline-Profil wird erstellt, auf dem die Tests ausgeführt werden. Die automatische Generierung bietet Nutzern zwar die beste Leistung, erhöht aber auch die Build-Zeit, da zwei Builds und Instrumentierungstests erforderlich sind.

Sie können dieses Verhalten auch pro Variante angeben, wie im folgenden Beispiel gezeigt:

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild = true
        }
    }
}

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

Im vorherigen Beispiel wird die Aufgabe generateFreeReleaseBaselineProfile beim Starten von assembleFreeRelease ausgeführt. Das ist hilfreich, wenn der Nutzer beispielsweise einen release-Build für die Verteilung haben möchte, bei dem das Profil immer beim Erstellen generiert wird, und einen releaseWithoutProfile-Build für interne Tests.

Anstatt eine neue Variante ohne Baseline-Profil hinzuzufügen, können Sie die Generierung auch über die Befehlszeile deaktivieren:

./gradlew assembleRelease -Pandroid.baselineProfile.automaticGenerationDuringBuild=false

Baseline-Profile in Quellen speichern

Sie können Baseline-Profile über das Flag saveInSrc im build.gradle.kts des Anwendungs- oder Bibliotheksmoduls im Quellverzeichnis speichern:

• true: Das Baseline-Profil wird in src/<variant>/generated/baselineProfiles gespeichert. So können Sie das zuletzt generierte Profil mit Ihren Quellen verknüpfen.
• false: Das Baseline-Profil wird in den Zwischendateien im Build-Verzeichnis gespeichert. So wird beim Committen des Codes nicht das zuletzt generierte Profil gespeichert.

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

Sie können dieses Verhalten auch pro Variante angeben:

baselineProfile {
    variants {
        freeRelease {
            saveInSrc = true
        }
    }
}

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

Warnungen deaktivieren

Standardmäßig warnt das Baseline Profile Gradle-Plug-in Sie vor Situationen, die Probleme verursachen könnten. Wenn Sie die Warnungen deaktivieren möchten, können Sie die entsprechende Option in Ihrer build.gradle.kts-Datei auf false setzen. Folgende Optionen sind verfügbar:

baselineProfile {
    warnings {

        /**
        * Warn when the Android Gradle Plugin version is higher than the max
        * tested one.
        */
        maxAgpVersion = true

        /**
        * Warn when a benchmark or baseline profile variant has been disabled.
        */
        disabledVariants = true

        /**
        * Warn that running `generateBaselineProfile` with AGP 8.0 doesn't
        * support running instrumentation tests for multiple build types at
        * once.
        */
        multipleBuildTypesWithAgp80 = true

        /**
        * Warn when no baseline profiles are generated after running the
        * generate baseline profile command.
        */
        noBaselineProfileRulesGenerated = true

        /**
        * Warn when no startup profiles are generated after running the generate
        * baseline profile command.
        */
        noStartupProfileRulesGenerated = true
    }
}

Profilregeln filtern

Mit dem Gradle-Plug-in für Baseline-Profile können Sie die generierten Baseline-Profilregeln filtern. Das ist besonders für Bibliotheken hilfreich, wenn Sie Profilregeln für Klassen und Methoden ausschließen möchten, die Teil anderer Abhängigkeiten der Beispiel-App oder der Bibliothek selbst sind. Mit den Filtern können bestimmte Pakete und Klassen ein- und ausgeschlossen werden. Wenn Sie nur Ausschlüsse angeben, werden nur übereinstimmende Regeln für das Baseline-Profil ausgeschlossen. Alles andere ist enthalten.

Die Filterspezifikation kann eine der folgenden sein:

• Paketname, der mit doppelten Platzhaltern endet, um dem angegebenen Paket und allen Unterpaketen zu entsprechen. Beispielsweise führt com.example.** zu Übereinstimmungen mit com.example.method und com.example.method.bar.
• Der Paketname endet mit einem Platzhalter, damit nur das angegebene Paket berücksichtigt wird. Beispiel: com.example.* stimmt mit com.example.method überein, aber nicht mit com.example.method.bar.
• Klassennamen, die einer bestimmten Klasse entsprechen, z. B. com.example.MyClass.

Die folgenden Beispiele zeigen, wie Sie bestimmte Pakete ein- und ausschließen:

baselineProfile {
    filter {
        include("com.somelibrary.widget.grid.**")
        exclude("com.somelibrary.widget.grid.debug.**")
        include("com.somelibrary.widget.list.**")
        exclude("com.somelibrary.widget.list.debug.**")
        include("com.somelibrary.widget.text.**")
        exclude("com.somelibrary.widget.text.debug.**")
    }
}

baselineProfile {
    filter {
        include 'com.somelibrary.widget.grid.**'
        exclude 'com.somelibrary.widget.grid.debug.**'
        include 'com.somelibrary.widget.list.**'
        exclude 'com.somelibrary.widget.list.debug.**'
        include 'com.somelibrary.widget.text.**'
        exclude 'com.somelibrary.widget.text.debug.**'
    }
}

So passen Sie die Filterregeln für verschiedene Varianten an:

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include("com.myapp.**") }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include("com.myapp.free.**")
            }
        }
        paid {
            filter {
                include("com.myapp.paid.**")
            }
        }
    }
}

// Build-type-specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include 'com.myapp.**' }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include 'com.myapp.free.**'
            }
        }
        paid {
            filter {
                include 'com.myapp.paid.**'
            }
        }
    }
}

// Build-type specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

Sie können Regeln auch mit dem Argument filterPredicate in BaselineProfileRule.collect() filtern. Wir empfehlen jedoch, das Gradle-Plug-in zum Filtern zu verwenden, da es eine einfachere Möglichkeit zum Filtern von Unterpaketen und einen einzigen Ort zum Konfigurieren des gesamten Moduls bietet.

Build-Typen für Benchmarks und Baseline-Profile anpassen

Das Baseline Profile Gradle-Plug-in erstellt zusätzliche Build-Typen, um die Profile zu generieren und Benchmarks auszuführen. Diese Build-Typen haben das Präfix benchmark und nonMinified. Für den Build-Typ release erstellt das Plug-in beispielsweise die Build-Typen benchmarkRelease und nonMinifiedRelease. Diese Build-Typen werden automatisch für den jeweiligen Anwendungsfall konfiguriert und müssen in der Regel nicht angepasst werden. Es gibt jedoch einige Fälle, in denen es dennoch sinnvoll sein kann, benutzerdefinierte Optionen anzuwenden, z. B. um eine andere Signaturkonfiguration zu verwenden.

Sie können die automatisch generierten Build-Typen mit einer Teilmenge der Build-Typ-Attribute anpassen. Attribute, die nicht verwendet werden können, werden überschrieben. Das folgende Beispiel zeigt, wie die zusätzlichen Build-Typen angepasst werden und welche Eigenschaften überschrieben werden:

android {
    buildTypes {
        release {
            ...
        }
        create("benchmarkRelease") {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default
            // it's the same as for the `release` build type).
            signingConfig = signingConfigs.getByName("benchmarkRelease")
        }
        create("nonMinifiedRelease") {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.getByName("nonMinifiedRelease")

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't
            // customize the following properties, which are always overridden to
            // avoid breaking Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false
        }
    }
}

android {
    buildTypes {
        release {
            ...
        }
        benchmarkRelease {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default it's the
            // same as for the `release` build type.)
            signingConfig = signingConfigs.benchmarkRelease
        }
        nonMinifiedRelease {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.nonMinifiedRelease

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't use
            // the following properties, which are always overridden to avoid breaking
            // Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false       
        }
    }
}

Zusätzliche Anmerkungen

Beim Erstellen von Baseline-Profilen sind einige zusätzliche Dinge zu beachten:

• Kompilierte Baseline-Profile dürfen maximal 1,5 MB groß sein. Dies gilt nicht für das Textformat in Ihren Quelldateien, die vor der Kompilierung in der Regel viel größer sind. Prüfen Sie die Größe Ihres binären Baseline-Profils, indem Sie es im Ausgabeartefakt unter assets/dexopt/baseline.prof für APK oder BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof für AAB suchen.

• Ungefähre Regeln, die zu viel von der Anwendung kompilieren, können den Start aufgrund des erhöhten Festplattenzugriffs verlangsamen. Wenn Sie gerade erst mit Baseline Profiles beginnen, müssen Sie sich darum keine Gedanken machen. Je nach App sowie Größe und Anzahl der Journeys kann das Hinzufügen vieler Journeys jedoch zu einer suboptimalen Leistung führen. Testen Sie die Leistung Ihrer App, indem Sie verschiedene Profile ausprobieren und prüfen, ob sich die Leistung nach den Ergänzungen verschlechtert.

Codelabs