Configurer la génération de profils de référence

Le plug-in Baseline Profile Gradle facilite la génération et la maintenance des profils de référence. Il vous aide à effectuer les tâches suivantes :

Cette page explique comment utiliser le plug-in Baseline Profile Gradle pour personnaliser la génération de vos profils de référence.

Configuration requise pour le plug-in

Utiliser des appareils gérés par Gradle pour générer des profils de référence

Pour générer votre profil de référence à l'aide d'un appareil géré par Gradle (GMD), ajoutez-en un dans la configuration build.gradle.kts du module du producteur de profil. Il s'agit probablement du module de test :baselineprofile, comme indiqué dans l'exemple suivant :

Kotlin

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

Groovy

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

Utiliser le GMD pour générer des profils de référence en l'ajoutant au profil de référence Configuration du plug-in Gradle comme suit, dans le build.gradle.kts du Module de test :baselineprofile:

Kotlin

baselineProfile {
    managedDevices += "pixel6Api31"
}

Groovy

baselineProfile {
    managedDevices = ['pixel6Api31']
}

Lorsque vous utilisez un GMD pour générer des profils de référence, définissez useConnectedDevices sur false, dans votre module de test :baselineprofile:

Kotlin

baselineProfile {
    ...
    useConnectedDevices = false
}

Groovy

baselineProfile {
    ...
    useConnectedDevices false
}

Générer des profils de référence pour différentes variantes

Vous pouvez générer des profils de référence par variante, par type ou sous forme de fichier unique à utiliser pour toutes les variantes. Contrôlez ce comportement via le paramètre de fusion, comme comme illustré dans l'exemple suivant, dans le build.gradle.kts du un module d'application ou de bibliothèque.

Kotlin

baselineProfile {
    mergeIntoMain = true
}

Groovy

baselineProfile {
    mergeIntoMain true
}

Pour fusionner les profils générés pour toutes les variantes dans un seul profil, définissez mergeIntoMain sur true. Il n'est pas possible de générer des profils de référence par variante lorsque ce paramètre est true. Il existe donc une seule tâche Gradle appelée generateBaselineProfile. Le profil est généré dans src/main/generated/baselineProfiles.

Pour désactiver la fusion et avoir un profil par variante, définissez mergeIntoMain sur false. Dans ce cas, il existe plusieurs tâches Gradle spécifiques aux variantes. Lorsqu'il existe deux types de produit (par exemple, un sans frais et l'autre payant) et un type de build, les tâches générées sont les suivantes :

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

Pour spécifier le comportement de fusion par variante, utilisez le code suivant :

Kotlin

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

Groovy

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

Dans l'exemple précédent, les variantes dans lesquelles l'indicateur est défini sur true sont toutes fusionnées dans src/main/generated/baselineProfiles, tandis que les profils des variantes dont l'indicateur est défini sur false sont conservés dans le dossier src/<variant>/generated/baselineProfiles.

Par défaut, mergeIntoMain est défini sur true pour les bibliothèques et sur false pour les applications.

Générer automatiquement des profils de référence lors de l'assemblage d'une nouvelle version

Vous pouvez configurer les profils de référence pour qu'ils soient générés automatiquement à chaque build au lieu d'utiliser manuellement la tâche generateBaselineProfile. Avec la génération automatique, le profil le plus à jour est inclus dans le build.

Pour activer la génération automatique pour les builds, utilisez l'indicateur automaticGenerationDuringBuild :

Kotlin

baselineProfile {
    automaticGenerationDuringBuild = true
}

Groovy

baselineProfile {
    automaticGenerationDuringBuild true
}

Définir l'indicateur automaticGenerationDuringBuild sur true déclenche la génération d'un nouveau profil de référence pour chaque assemblage de version. Cela signifie que l'exécution d'une tâche d'assemblage de build, telle que ./gradlew:app:assembleRelease, déclenche également :app:generateReleaseBaselineProfile, lance les tests d'instrumentation du profil de référence et compile le build du profil de référence sur lequel ils s'exécutent. Bien que la génération automatique permette aux utilisateurs de bénéficier des meilleures performances, elle augmente également la durée de la compilation en raison des doubles tests de compilation et d'instrumentation.

Vous pouvez également spécifier ce comportement par variante, comme illustré dans l'exemple suivant :

Kotlin

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

Groovy

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

Dans l'exemple précédent, la tâche generateFreeReleaseBaselineProfile s'exécute au démarrage de assembleFreeRelease. Cela peut être utile lorsque l'utilisateur souhaite disposer, par exemple, d'une release pour un build de distribution qui génère toujours le profil lors de la compilation, et d'un build releaseWithoutProfile pour les tests internes.

Stocker les profils de référence dans des sources

Vous pouvez stocker les profils de référence dans le répertoire source via l'saveInSrc dans le build.gradle.kts du module d'application ou de bibliothèque:

  • true : le profil de référence est stocké dans src/<variant>/generated/baselineProfiles. Cela vous permet de valider le dernier profil généré avec vos sources.
  • false : le profil de référence est stocké dans les fichiers intermédiaires du répertoire de compilation. Lorsque vous validez votre code, vous n'enregistrez donc pas le dernier profil généré.

Kotlin

baselineProfile {
    saveInSrc = true
}

Groovy

baselineProfile {
    saveInSrc true
}

Vous pouvez également spécifier le comportement suivant par variante :

Kotlin

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

Groovy

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

Filtrer les règles de profil

Le plug-in Baseline Profile Gradle vous permet de filtrer les règles de profil de référence générées. Cette approche est particulièrement utile pour les bibliothèques, si vous souhaitez exclure des règles de profil pour les classes et les méthodes qui font partie d'autres dépendances de l'application exemple ou de la bibliothèque. Les filtres peuvent inclure et exclure des packages et des classes spécifiques. Lorsque vous spécifiez uniquement des exclusions, seules les règles correspondantes du profil de référence sont exclues. Les autres sont incluses.

La spécification des filtres peut se présenter comme suit :

  • Nom de package se terminant par des caractères génériques doubles pour correspondre au package spécifié et à tous les sous-packages. Par exemple, com.example.** correspond à com.example.method et com.example.method.bar.
  • Nom de package se terminant par un caractère générique pour correspondre uniquement au package spécifié. Par exemple, com.example.* correspond à com.example.method, mais pas à com.example.method.bar.
  • Noms de classe correspondant à une classe spécifique, par exemple com.example.MyClass.

Les exemples suivants montrent comment inclure et exclure des packages spécifiques :

Kotlin

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.**")
    }
}

Groovy

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

Personnalisez les règles de filtrage pour différentes variantes comme suit :

Kotlin

// 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.**")
            }
        }
    }
}

Groovy

// 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.**'
            }
        }
    }
}

Vous pouvez également filtrer les règles à l'aide de l'argument filterPredicate dans BaselineProfileRule.collect(), mais nous vous recommandons d'utiliser le plug-in Gradle, qui permet de filtrer plus facilement les sous-packages et de centraliser la configuration de l'ensemble du module.

Personnaliser les types de compilation "benchmark" et "profil de référence"

Le plug-in Baseline Profile Gradle crée des types de compilation supplémentaires à générer les profils et les analyses comparatives. Ces types de compilation sont précédés du préfixe benchmark et nonMinified. Par exemple, pour le type de compilation release, le plug-in crée les types de compilation benchmarkRelease et nonMinifiedRelease. Ces types de compilation sont automatiquement configurés pour le cas d'utilisation spécifique n'ont généralement pas besoin de personnalisation. Toutefois, dans certains cas, il peut être utile d'appliquer des options personnalisées, par exemple pour appliquer une configuration de signature différente.

Vous pouvez personnaliser les types de compilation générés automatiquement à l'aide d'un sous-ensemble de les propriétés du type de compilation ; les propriétés non utilisables sont remplacées. L'exemple suivant montre comment personnaliser les types de compilation supplémentaires et les propriétés ignorées :

Kotlin

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

Groovy

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

Remarques supplémentaires

Lorsque vous créez des profils de référence, gardez à l'esprit les points suivants :

  • La taille des profils de référence compilés doit être inférieure à 1,5 Mo. Cela ne s'applique pas au format de texte de vos fichiers sources, qui sont généralement beaucoup plus volumineux avant la compilation. Vérifiez la taille du profil de référence de votre binaire en le recherchant dans l'artefact de sortie sous assets/dexopt/baseline.prof pour l'APK ou BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof pour l'AAB.

  • Les règles générales qui compilent une trop grande partie de l'application peuvent ralentir le démarrage en raison de l'augmentation des accès au disque. Si vous débutez avec les profils de référence, vous n'avez pas à vous en soucier. Toutefois, selon votre application, ainsi que la taille et le nombre de parcours, l'ajout de nombreux parcours peut nuire aux performances. Testez les performances de votre application en essayant différents profils et en vérifiant que les performances ne régressent pas après les ajouts.

Ateliers de programmation

Découvrez comment utiliser le macrobenchmarking pour mesurer les performances.
En savoir plus
Générez un profil de référence personnalisé spécifiquement adapté à une application Android, et vérifiez son efficacité.
En savoir plus
Précédent
Créer des profils de référence pour une bibliothèque
Suivant
Mesurer avec la bibliothèque Macrobenchmark