Generieren des Baseline-Profils konfigurieren

Das Gradle-Plug-in für Baseline-Profile erleichtert das Erstellen und Pflegen von Baseline-Profilen. Sie können damit Folgendes tun:

• Erstellen Sie neue Baseline-Profile für Ihre App.
• Erstellen Sie neue Baseline-Profile für Ihre Bibliothek.
• Generierung des Baseline-Profils anpassen

Auf dieser Seite wird erläutert, wie Sie mit dem Gradle-Plug-in für Baseline-Profile die Generierung Ihrer Baseline-Profile anpassen.

Plug-in-Anforderungen

• AGP 8.0 oder höher
• Abhängigkeit von der aktuellen Version des Gradle-Plug-ins

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

Wenn Sie ein Gradle Managed Device (GMD) zum Generieren Ihres Baseline-Profils verwenden möchten, fügen Sie es in der build.gradle.kts-Konfiguration des Profilerstellungsmoduls hinzu – wahrscheinlich das :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 die GMD, um Baseline-Profile zu generieren. Fügen Sie sie dazu der Gradle-Plug-in-Konfiguration für Baseline-Profile im build.gradle.kts des :baselineprofile-Testmoduls wie unten beschrieben hinzu:

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

Wenn Sie mit einer GMD Baseline-Profile generieren, legen Sie in Ihrem :baselineprofile-Testmodul useConnectedDevices auf false fest:

baselineProfile {
    ...
    useConnectedDevices = false
}

baselineProfile {
    ...
    useConnectedDevices false
}

Baseline-Profile für verschiedene Varianten generieren

Sie können Baseline-Profile pro Variante, pro Variante oder als einzelne Datei generieren, die für alle Varianten verwendet werden kann. Dieses Verhalten lässt sich über die Einstellung „Merge“ steuern, wie im folgenden Beispiel in der 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, ist es nicht möglich, Baseline-Profile pro Variante zu generieren. Es gibt also nur eine einzelne Gradle-Aufgabe namens generateBaselineProfile. Das Profil wird unter src/main/generated/baselineProfiles ausgegeben.

Wenn Sie die Zusammenführung deaktivieren und ein Profil pro Variante haben möchten, legen Sie für mergeIntoMain den Wert false fest. In diesem Fall gibt es mehrere variantenspezifische Gradle-Aufgaben. Wenn es beispielsweise zwei Varianten gibt, z. B. eine kostenlose und eine kostenpflichtige, und einen Release-Buildtyp, sind die Aufgaben folgende:

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

Verwenden Sie den folgenden Code, um das Zusammenführungsverhalten pro Variante anzugeben:

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

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

Im vorherigen Beispiel werden die Varianten, bei denen das Flag auf true festgelegt ist, alle in src/main/generated/baselineProfiles zusammengeführt, während die Profile für die Varianten, bei denen das Flag auf false festgelegt 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 eines neuen Releases automatisch generieren

Sie können Baseline-Profile so konfigurieren, dass sie automatisch bei jedem Release-Build generiert werden, anstatt sie manuell mit der Aufgabe generateBaselineProfile zu erstellen. Bei der automatischen Generierung ist das aktuelle Profil im Release-Build enthalten.

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. Das bedeutet, dass durch Ausführen einer Build-Aufgabe für die Zusammenstellung einer Release-Version, z. B. ./gradlew:app:assembleRelease, auch :app:generateReleaseBaselineProfile ausgelöst wird, die Instrumentierungstests für das Baseline-Profil gestartet und der Build für das Baseline-Profil erstellt wird, auf dem sie ausgeführt werden. Die automatische Generierung hilft Nutzern zwar, die beste Leistung zu erzielen, verlängert aber auch die Buildzeit aufgrund der doppelten Build- und Instrumentierungstests.

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 ausgeführt, wenn assembleFreeRelease gestartet wird. Das ist hilfreich, wenn der Nutzer beispielsweise einen release-Build für den Distributionsbuild haben möchte, der das Profil beim Erstellen immer generiert, und einen releaseWithoutProfile-Build für interne Tests.

Baseline-Profile in Quellen speichern

Sie können Baseline-Profile über das Flag saveInSrc in der 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 übernehmen.
• false: Das Baseline-Profil wird in den Zwischendateien im Build-Verzeichnis gespeichert. So speichern Sie beim Committen Ihres Codes nicht das zuletzt generierte Profil.

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

Sie können dieses Verhalten auch pro Variante festlegen:

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

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

Warnungen deaktivieren

Standardmäßig warnt das Gradle-Plug-in für das Baseline-Profil vor Situationen, die zu Problemen führen können. Wenn Sie die Warnungen deaktivieren möchten, können Sie die entsprechende Option in der build.gradle.kts-Datei auf false setzen. Folgende Warnoptionen 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
    }
}

Filterregeln für Profile

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

Die Filterauswahl kann eine der folgenden sein:

• Paketname, der auf doppelte Platzhalter 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.
• Paketname, der auf einen Platzhalter endet, um nur mit dem angegebenen Paket übereinzustimmen. Beispiel: com.example.* stimmt mit com.example.method überein, aber nicht mit com.example.method.bar.
• Klassennamen, die mit einer bestimmten Klasse übereinstimmen, 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 bietet und an einem einzigen Ort das gesamte Modul konfiguriert werden kann.

Buildtypen für Benchmarks und Baseline-Profile anpassen

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

Sie können die automatisch generierten Buildtypen mithilfe eines Teils der Buildtyp-Eigenschaften anpassen. Nicht nutzbare Eigenschaften werden überschrieben. Im folgenden Beispiel wird gezeigt, wie Sie die zusätzlichen Buildtypen anpassen 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

Beachten Sie beim Erstellen von Baseline-Profilen Folgendes:

• Kompilierte Baseline-Profile müssen kleiner als 1,5 MB sein. Das 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. Suchen Sie dazu im Ausgabeartefakt unter assets/dexopt/baseline.prof für APK oder BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof für AAB.

• Grobe Regeln, die zu viel der Anwendung kompilieren, können den Start aufgrund des erhöhten Laufwerkszugriffs verlangsamen. Wenn Sie gerade erst mit Baseline-Profilen beginnen, ist das kein Problem. Je nach App und Größe und Anzahl der Fahrten kann das Hinzufügen vieler Fahrten 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 nicht verschlechtert.

Codelabs