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 :

• Créer des profils de référence pour votre application
• Créer des profils de référence pour votre bibliothèque
• Personnaliser la génération de profils de référence

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

• AGP 8.0 ou version ultérieure
• Dépendance à la dernière version du plug-in Gradle

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 :

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

Utilisez le GMD pour générer des profils de référence en l'ajoutant à la configuration du plug-in Baseline Profile Gradle comme suit :

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

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

baselineProfile {
    ...
    useConnectedDevices = false
}

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 indiqué dans l'exemple suivant.

baselineProfile {
    mergeIntoMain = true
}

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 :

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

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 :

baselineProfile {
    automaticGenerationDuringBuild = true
}

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 :

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

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'indicateur saveInSrc :

• 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é.

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

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

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

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 :

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

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

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

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 d'analyse comparative et de profil de référence

Le plug-in Baseline Profile Gradle crée des types de compilation supplémentaires pour générer les profils et exécuter des analyses comparatives. Ces types de compilation sont précédés de 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 et ne nécessitent généralement aucune personnalisation. Toutefois, dans certains cas, il peut être utile d'appliquer des options personnalisées, par exemple pour appliquer une autre configuration de signature.

Vous pouvez personnaliser les types de compilation générés automatiquement à l'aide d'un sous-ensemble de propriétés de 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 quelles propriétés sont remplacées:

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.getByName("benchmarkRelease")
        }
        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       
        }
    }
}

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