Configura la generazione del profilo di riferimento

Il plug-in Gradle per i profili di base semplifica la generazione e la manutenzione dei profili di base. Ti aiuta a svolgere le seguenti attività:

• Crea nuovi profili di base per la tua app.
• Crea nuovi profili di base per la tua libreria.
• Personalizza la generazione del profilo di base.

Questa pagina spiega come utilizzare il plug-in Gradle per i profili di base per personalizzare la generazione dei profili di base.

Requisiti dei plug-in

• AGP 8.0 o versioni successive
• Dipendenza dall'ultima versione del plug-in Gradle

Utilizzare un dispositivo gestito da Gradle per generare profili di base

Per utilizzare un Gradle Managed Device (GMD) per generare il profilo di base, aggiungine uno nella configurazione build.gradle.kts del modulo di produzione del profilo, probabilmente il modulo di test :baselineprofile, come mostrato nell'esempio seguente:

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

Utilizza GMD per generare profili di base aggiungendolo alla configurazione del plug-in Gradle del profilo di base come segue, in build.gradle.kts del modulo di test :baselineprofile:

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

Quando utilizzi un GMD per generare profili di base, imposta useConnectedDevices su false nel modulo di test :baselineprofile:

baselineProfile {
    ...
    useConnectedDevices = false
}

baselineProfile {
    ...
    useConnectedDevices false
}

Genera profili di base per varianti diverse

Puoi generare profili di base per variante, per sapore o come singolo file da utilizzare per tutte le varianti. Controlla questo comportamento tramite l'impostazione di unione, come mostrato nell'esempio seguente, nel build.gradle.kts del modulo dell'applicazione o della libreria.

baselineProfile {
    mergeIntoMain = true
}

baselineProfile {
    mergeIntoMain true
}

Per unire i profili generati per tutte le varianti in un unico profilo, imposta mergeIntoMain su true. Non è possibile generare profili di base per variante quando questa impostazione è true, quindi esiste un'unica attività Gradle chiamata generateBaselineProfile. Il profilo viene generato in src/main/generated/baselineProfiles.

Per disattivare l'unione e avere un profilo per variante, imposta mergeIntoMain su false. In questo caso, esistono più attività Gradle specifiche per le varianti. Ad esempio, quando esistono due versioni, ad esempio senza costi e a pagamento, e un tipo di build di rilascio, le attività sono le seguenti:

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

Per specificare il comportamento di unione per variante, utilizza il seguente codice:

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

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

Nell'esempio precedente, le varianti in cui il flag è impostato su true vengono tutte unite in src/main/generated/baselineProfiles, mentre i profili delle varianti in cui il flag è impostato su false vengono mantenuti nella cartella src/<variant>/generated/baselineProfiles.

Per impostazione predefinita, mergeIntoMain è impostato su true per le librerie e su false per le app.

Generare automaticamente i profili di base durante l'assemblaggio di una nuova release

Puoi configurare i profili di base in modo che vengano generati automaticamente a ogni build di release, anziché utilizzare manualmente l'attività generateBaselineProfile. Con la generazione automatica, il profilo più aggiornato viene incluso nella build di rilascio.

Per attivare la generazione automatica per le build di rilascio, utilizza il flag automaticGenerationDuringBuild:

baselineProfile {
    automaticGenerationDuringBuild = true
}

baselineProfile {
    automaticGenerationDuringBuild true
}

L'impostazione del flag automaticGenerationDuringBuild su true attiva la generazione di un nuovo profilo di base per ogni assembly di release. Ciò significa che l'esecuzione di un'attività di build di release di assemblaggio, come ./gradlew:app:assembleRelease, attiva anche :app:generateReleaseBaselineProfile, avvia i test di strumentazione del profilo di base e crea la build del profilo di base su cui vengono eseguiti. Sebbene la generazione automatica aiuti gli utenti a ottenere il miglior vantaggio in termini di rendimento, aumenta anche il tempo di compilazione a causa dei test di compilazione e strumentazione doppi.

Puoi anche specificare questo comportamento per variante, come mostrato nel seguente esempio:

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

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

Nell'esempio precedente, l'attività generateFreeReleaseBaselineProfile viene eseguita all'avvio di assembleFreeRelease. Ciò è utile quando l'utente vuole, ad esempio, una release per la build di distribuzione che genera sempre il profilo durante la creazione e una build releaseWithoutProfile per i test interni.

Invece di aggiungere una nuova variante senza un profilo di base, puoi anche disattivare la generazione dalla riga di comando nel seguente modo:

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

Memorizzare i profili di base nelle origini

Puoi archiviare i profili di base nella directory di origine tramite il flag saveInSrc nel file build.gradle.kts del modulo dell'applicazione o della libreria:

• true: il profilo di base è memorizzato in src/<variant>/generated/baselineProfiles. In questo modo puoi eseguire il commit dell'ultimo profilo generato con le tue fonti.
• false: il profilo di base è archiviato nei file intermedi nella directory di build. In questo modo, quando esegui il commit del codice, non salvi l'ultimo profilo generato.

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

Puoi anche specificare questo comportamento per variante:

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

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

Disattivare gli avvisi

Per impostazione predefinita, il plug-in Gradle per i profili di base ti avvisa di situazioni che potrebbero causare problemi. Per disattivare gli avvisi, puoi impostare l'opzione pertinente su false nel file build.gradle.kts. Ecco le opzioni di avviso:

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

Filtrare le regole del profilo

Il plug-in Gradle per i profili di base consente di filtrare le regole dei profili di base generate. Ciò è particolarmente utile per le librerie, se vuoi escludere le regole del profilo per le classi e i metodi che fanno parte di altre dipendenze dell'app di esempio o della libreria stessa. I filtri possono includere ed escludere pacchetti e classi specifici. Quando specifichi solo le esclusioni, vengono escluse solo le regole del profilo di base corrispondenti e tutto il resto viene incluso.

La specifica dei filtri può essere una delle seguenti:

• Nome del pacchetto che termina con caratteri jolly doppi per corrispondere al pacchetto specificato e a tutti i sottopacchetti. Ad esempio, com.example.** corrisponde a com.example.method e com.example.method.bar.
• Nome del pacchetto che termina con un carattere jolly per corrispondere solo al pacchetto specificato. Ad esempio, com.example.* corrisponde a com.example.method, ma non a com.example.method.bar.
• Nomi delle classi per trovare una classe specifica, ad esempio com.example.MyClass.

Gli esempi riportati di seguito mostrano come includere ed escludere pacchetti specifici:

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

Personalizza le regole di filtro per le diverse varianti nel seguente modo:

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

Puoi anche filtrare le regole utilizzando l'argomento filterPredicate in BaselineProfileRule.collect(), ma ti consigliamo di utilizzare il plug-in Gradle per filtrare perché offre un modo più semplice per filtrare i pacchetti secondari e un unico punto in cui configurare l'intero modulo.

Personalizzare i tipi di build di benchmark e profili di base

Il plug-in Gradle per i profili di base crea tipi di build aggiuntivi per generare i profili ed eseguire benchmark. Questi tipi di build hanno come prefisso benchmark e nonMinified. Ad esempio, per il tipo di build release, il plug-in crea i tipi di build benchmarkRelease e nonMinifiedRelease. Questi tipi di build vengono configurati automaticamente per il caso d'uso specifico e in genere non richiedono alcuna personalizzazione. Tuttavia, in alcuni casi potrebbe essere utile applicare alcune opzioni personalizzate, ad esempio per applicare una configurazione di firma diversa.

Puoi personalizzare i tipi di build generati automaticamente utilizzando un sottoinsieme di proprietà del tipo di build; le proprietà non utilizzabili vengono sostituite. L'esempio seguente mostra come personalizzare i tipi di build aggiuntivi e quali proprietà vengono sostituite:

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

Note aggiuntive

Quando crei profili di base, ecco alcune cose aggiuntive da tenere presente:

• I profili di base compilati devono avere dimensioni inferiori a 1,5 MB. Ciò non si applica al formato di testo nei file di origine, che in genere sono molto più grandi prima della compilazione. Verifica le dimensioni del profilo di base binario individuandolo nell'artefatto di output in assets/dexopt/baseline.prof per l'APK o BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof per l'AAB.

• Regole generali che compilano troppa parte dell'applicazione possono rallentare l'avvio a causa dell'aumento dell'accesso al disco. Se hai appena iniziato a utilizzare i profili di base, non preoccuparti. Tuttavia, a seconda dell'app e delle dimensioni e del numero di viaggi, l'aggiunta di molti viaggi può comportare prestazioni non ottimali. Testa le prestazioni della tua app provando diversi profili e verificando che le prestazioni non peggiorino dopo le aggiunte.

Codelab