建立基準設定檔

您可以使用 Jetpack Macrobenchmark 程式庫和 BaselineProfileRule，自動產生每個應用程式版本的設定檔。建議您使用 com.android.tools.build:gradle:8.0.0 以上版本，因為這些版本強化了使用基準設定檔時的建構功能。

以下是建立新基準設定檔的一般步驟：

  1. 設定基準設定檔模組。
  2. 定義有助於產生基準設定檔的 JUnit 測試。
  3. 新增要最佳化的關鍵使用者歷程 (CUJ)。
  4. 產生基準設定檔。

產生基準設定檔後，請使用實體裝置進行基準測試，以測量速度改善情形。

使用 AGP 8.2 以上版本建立新的基準設定檔

如要建立新的基準設定檔，最簡單的方法是使用基準設定檔模組範本，自 Android Studio Iguana 和 Android Gradle 外掛程式 (AGP) 8.2 版開始可使用此範本。

Android Studio 基準設定檔產生器模組範本會自動建立新的模組，以便產生基準設定檔並進行基準測試。執行範本後，會產生大多數的一般建構設定、基準設定檔和驗證碼。這個範本會建立程式碼來產生基準設定檔並進行基準測試，進而評估應用程式的啟動情況。

設定基準設定檔模組

如要執行基準設定檔模組範本，請按照下列步驟操作：

  1. 依序選取「File」>「New」>「New Module」
  2. 在「Templates」面板中選取「Baseline Profile Generator」範本，然後進行設定：
    圖 1. 基準設定檔產生器模組範本。

    範本中的欄位如下：

    • Target application：定義要替哪個應用程式產生基準設定檔。如果專案中只有一個應用程式模組，這份清單中只會有一個項目。
    • Module name：您希望建立的基準設定檔模組採用的名稱。
    • Package name：您希望基準設定檔模組使用的套件名稱。
    • Language：指定您希望產生的程式碼採用 Kotlin 還是 Java。
    • Build configuration language：指定您要使用 Kotlin 指令碼 (KTS) 還是 Groovy 做為建構設定指令碼。
    • 使用 Gradle 管理的裝置：您是否使用 Gradle 管理的裝置測試應用程式。
  3. 按一下「Finish」，系統便會建立新模組。如果使用來源控制項，系統可能會提示您在其中加入新建立的模組檔案。

定義基準設定檔產生器

在新建立的模組中含有的測試，可產生基準設定檔並進行基準測試，如果您只要測試基本的應用程式啟動也不成問題。建議您擴充這些功能，以納入 CUJ 和進階啟動工作流程。請確保所有與應用程式啟動作業相關的測試都位於 rule 區塊中，且 includeInStartupProfile 設為 true；相反地，為獲得最佳效能，請確保與應用程式啟動作業無關的任何測試都不包含在啟動設定檔中。應用程式啟動最佳化功能是用來定義基準設定檔的特殊部分，稱為啟動設定檔。

如果您要在產生的基準設定檔和基準程式碼外擷取這些 CUJ，好讓這些 CUJ 可以同時用於兩者，以上做法有助於確保可維護性。也就是說，對 CUJ 所做的變更會以一致的方式使用。

產生並安裝基準設定檔

基準設定檔模組範本會新增一個執行設定，以便產生基準設定檔。如果使用變種版本，Android Studio 會建立多個執行設定，讓您為每個變種版本產生不同的基準設定檔。

產生基準設定檔執行設定。
圖 2. 執行這項設定會產生基準設定檔。

「Generate Baseline Profile」執行設定完成之後，系統會分析模組，並將產生的基準設定檔複製到該模組的 src/variant/generated/baselineProfiles/baseline-prof.txt 中。變化版本選項可以是發布子版本類型，也可以是與發布子版本類型相關的建構變化版本。

產生的基準設定檔最初是在 build/outputs 中建立。完整路徑取決於要分析的應用程式採用哪個變化/變種版本，以及您在剖析時使用的是 Gradle 管理的裝置，還是已連結的裝置。如果您使用的名稱，同樣由範本產生的程式碼和建構設定所用，則基準設定檔會建立在 build/outputs/managed_device_android_test_additional_output/nonminifiedrelease/pixel6Api31/BaselineProfileGenerator_generate-baseline-prof.txt 檔案中。您可能不需要直接與這個版本產生的基準設定檔互動，除非您手動將設定檔複製到目標模組 (不建議)。

使用 AGP 8.1 建立新的基準設定檔

如果無法使用基準設定檔模組範本，請使用 Macrobenchmark 模組範本和基準設定檔 Gradle 外掛程式建立新的基準設定檔。從 Android Studio Giraffe 和 AGP 8.1 開始，建議您使用這些工具。

如要使用 Macrobenchmark 模組範本和基準設定檔 Gradle 外掛程式建立新的基準設定檔，請按照以下步驟操作：

  1. 在 Gradle 專案中設定 Macrobenchmark 模組。
  2. 定義名為 BaselineProfileGenerator 的新類別：
    class BaselineProfileGenerator {
    @get:Rule
    val baselineProfileRule = BaselineProfileRule()

    @Test
    fun startup() = baselineProfileRule.collect(
        packageName = "com.example.app",
        profileBlock = {
            startActivityAndWait()
        }
    )
}

    產生器可以涵蓋應用程式啟動之外的互動作業，協助您改進應用程式的執行階段效能，例如捲動清單、執行動畫及瀏覽 Activity。您可以查看其他測試範例，瞭解如何使用 @BaselineProfileRule 改進關鍵使用者歷程。

  3. 新增基準設定檔 Gradle 外掛程式 (libs.plugins.androidx.baselineprofile)，可更輕鬆地產生基準設定檔，且方便日後維護。

  4. 如要產生基準設定檔，請在終端機中執行 :app:generateBaselineProfile 或 :app:generateVariantBaselineProfile Gradle 工作。

    您可以在已啟用 Root 權限的實體裝置、模擬器或 Gradle 管理的裝置上執行產生器，進行檢測設備測試。如果使用 Gradle 管理的裝置，請將 aosp 設為 systemImageSource，因為您需要基準設定檔產生器的 Root 存取權。

    產生工作結束時，基準設定檔會複製到 app/src/variant/generated/baselineProfiles。

不使用範本建立新的基準設定檔

我們建議使用 Android Studio 基準設定檔模組範本 (建議做法) 或 Macrobenchmark 範本建立基準設定檔，但您也可以只使用基準設定檔 Gradle 外掛程式。如要進一步瞭解基準設定檔 Gradle 外掛程式，請參閱「設定基準設定檔產生作業」。

以下說明如何直接使用基準設定檔 Gradle 外掛程式建立基準設定檔：

  1. 建立新的 com.android.test 模組，例如 :baseline-profile。

  2. 為 :baseline-profile 設定 build.gradle.kts 檔案：

    1. 套用 androidx.baselineprofile 外掛程式。
    2. 確認 targetProjectPath 指向 :app 模組。
    3. 視需要新增 Gradle 管理的裝置 (GMD)，在以下範例中為 pixel6Api31。如未指定，外掛程式會使用已連線的模擬裝置或實體裝置。
    4. 套用所需設定，如以下範例所示。

    Kotlin

    plugins {
    id("com.android.test")
    id("androidx.baselineprofile")
}

android {
    defaultConfig {
        ...
    }

    // Point to the app module, the module that you're generating the Baseline Profile for.
    targetProjectPath = ":app"
    // Configure a GMD (optional).
    testOptions.managedDevices.devices {
        pixel6Api31(com.android.build.api.dsl.ManagedVirtualDevice) {
            device = "Pixel 6"
            apiLevel = 31
            systemImageSource = "aosp"
        }
    }
}

dependencies { ... }

// Baseline Profile Gradle plugin configuration. Everything is optional. This
// example uses the GMD added earlier and disables connected devices.
baselineProfile {
    // Specifies the GMDs to run the tests on. The default is none.
    managedDevices += "pixel6Api31"
    // Enables using connected devices to generate profiles. The default is
    // `true`. When using connected devices, they must be rooted or API 33 and
    // higher.
    useConnectedDevices = false
}

    Groovy

    plugins {
    id 'com.android.test'
    id 'androidx.baselineprofile'
}

android {
    defaultConfig {
        ...
    }

    // Point to the app module, the module that you're generating the Baseline Profile for.
    targetProjectPath ':app'
    // Configure a GMD (optional).
    testOptions.managedDevices.devices {
        pixel6Api31(com.android.build.api.dsl.ManagedVirtualDevice) {
            device 'Pixel 6'
            apiLevel 31
            systemImageSource 'aosp'
        }
    }
}

dependencies { ... }

// Baseline Profile Gradle plugin configuration. Everything is optional. This
// example uses the GMD added earlier and disables connected devices.
baselineProfile {
    // Specifies the GMDs to run the tests on. The default is none.
    managedDevices ['pixel6Api31']
    // Enables using connected devices to generate profiles. The default is
    // `true`. When using connected devices, they must be rooted or API 33 and
    // higher.
    useConnectedDevices false
}

  3. 在 :baseline-profile 測試模組中建立基準設定檔測試。以下範例是啟動應用程式並等待閒置狀態的測試。

    Kotlin

    class BaselineProfileGenerator {

    @get:Rule
    val baselineRule = BaselineProfileRule()

    @Test
    fun startupBaselineProfile() {
        baselineRule.collect("com.myapp") {
            startActivityAndWait()
        }
    }
}

    Java

    public class BaselineProfileGenerator {

    @Rule
    Public BaselineProfileRule baselineRule = new BaselineProfileRule();

    @Test
    Public void startupBaselineProfile() {
        baselineRule.collect(
            "com.myapp",
            (scope -> {
                scope.startActivityAndWait();
                Return Unit.INSTANCE;
            })
        )
    }
}

  4. 更新應用程式模組中的 build.gradle.kts 檔案，例如 :app。

    1. 套用外掛程式 androidx.baselineprofile。
    2. 將 baselineProfile 依附元件新增至 :baseline-profile 模組。

    Kotlin

    plugins {
    id("com.android.application")
    id("androidx.baselineprofile")
}

android {
    // There are no changes to the `android` block.
    ...
}

dependencies {
    ...
    // Add a `baselineProfile` dependency on the `:baseline-profile` module.
    baselineProfile(project(":baseline-profile"))
}

    Groovy

    plugins {
    id 'com.android.application'
    id 'androidx.baselineprofile'
}

android {
    // No changes to the `android` block.
    ...
}

dependencies {
    ...
    // Add a `baselineProfile` dependency on the `:baseline-profile` module.
    baselineProfile ':baseline-profile"'
}

  5. 執行 :app:generateBaselineProfile 或 :app:generateVariantBaselineProfile Gradle 工作來產生設定檔。

  6. 產生工作結束時，基準設定檔會複製到 app/src/variant/generated/baselineProfiles。

使用 AGP 7.3-7.4 建立新的基準設定檔

您可以使用 AGP 7.3-7.4 產生基準設定檔，但我們強烈建議您升級至 AGP 8.1 以上版本，以便使用基準設定檔 Gradle 外掛程式及其最新功能。

如果您需要使用 AGP 7.3-7.4 建立基準設定檔，步驟與 AGP 8.1 的步驟相同，但有以下例外：

  • 請勿新增基準設定檔 Gradle 外掛程式。
  • 如要產生基準設定檔，請執行 Gradle 工作 ./gradlew [emulator name][flavor][build type]AndroidTest，例如 ./gradlew :benchmark:pixel6Api31BenchmarkAndroidTest。
  • 您必須手動將產生的基準設定檔規則套用至程式碼。

手動套用產生的規則

基準設定檔產生器會在裝置上建立人類可讀格式 (HRF) 的文字檔案，並將該檔案複製到主體機器。如要將產生的設定檔套用至程式碼，請按照下列步驟操作：

  1. 在產生設定檔的模組建構資料夾中找出 HRF 檔案：[module]/build/outputs/managed_device_android_test_additional_output/[device]。

    設定檔的命名模式為 [class name]-[test method name]-baseline-prof.txt，具體如下所示：BaselineProfileGenerator-startup-baseline-prof.txt。

  2. 將產生的設定檔複製到 src/main/，並將檔案重新命名為 baseline-prof.txt。

  3. 在應用程式 build.gradle.kts 檔案中的 ProfileInstaller 程式庫內新增依附元件，這樣才能在無法使用雲端設定檔的位置啟用本機基準設定檔編譯功能。這是在本機側載基準設定檔的唯一方法。

    dependencies {
     implementation("androidx.profileinstaller:profileinstaller:1.3.1")
}

  4. 建構正式版應用程式，而套用的 HRF 規則會編譯為二進位檔格式，附在 APK 或 AAB 中。接下來，請照常發布應用程式。

對基準設定檔進行基準測試

空白邊動作會執行 StartupBenchmarks.kt 或 StartupBencharks.java 中定義的基準測試。如要對基準設定檔進行基準測試，請透過空白邊動作建立新的「Android 檢測設備測試執行」設定。如要進一步瞭解基準測試，請參閱「建立 Macrobenchmark 類別」和「利用 Macrobenchmark 程式庫進行自動化評估」。

圖 3. 透過空白邊動作執行 Android 測試。

在 Android Studio 中執行這項操作時，建構輸出內容中會包含基準設定檔提供的速度改善項目詳細資料：

StartupBenchmarks_startupCompilationBaselineProfiles
timeToInitialDisplayMs   min 161.8,   median 178.9,   max 194.6
StartupBenchmarks_startupCompilationNone
timeToInitialDisplayMs   min 184.7,   median 196.9,   max 202.9

擷取所有必要程式碼路徑

有兩個重要指標可以測量應用程式啟動時間：

初始顯示時間 (TTID)
顯示應用程式 UI 第一個影格所需的時間。
完整顯示時間 (TTFD)
包括在初始影格顯示後，以非同步載入方式顯示內容所需的時間。

呼叫 ComponentActivity 的 reportFullyDrawn() 方法後，系統就會回報 TTFD。如果從未呼叫 reportFullyDrawn()，系統會改為回報 TTID。您可能需要將呼叫 reportFullyDrawn() 的時間延後到非同步載入作業完成後。舉例來說，如果 UI 包含 RecyclerView 或 Lazy 清單等動態清單，填入清單的背景工作可能是在清單首次繪製後才完成，也因此是在 UI 標示為已完成繪製後才完成。在這種情況下，在 UI 達到完成繪製狀態後執行的程式碼，不會納入基準設定檔。

如要將清單填入作業納入基準設定檔，請使用 getFullyDrawnReporter() 取得 FullyDrawnReporter，然後在應用程式程式碼中新增回報器。一旦背景工作完成清單填入作業，請立即釋放回報器。等到所有回報器都已釋放後，FullyDrawnReporter 才會呼叫 reportFullyDrawn() 方法。如此一來，基準設定檔就會包含填入清單所需的程式碼路徑。對使用者而言，這不會改變應用程式行為，但可讓基準設定檔包含所需的全部程式碼路徑。

如果應用程式使用 Jetpack Compose，請使用下列 API 表示已完成繪製的狀態：

  • ReportDrawn 表示可組合項可立即準備好進行互動。
  • ReportDrawnWhen 會使用 list.count > 0 等述詞，表示可組合項何時能準備好進行互動。
  • ReportDrawnAfter 會採用暫停方法，完成後就會表示可組合項已準備好進行互動。
上一頁
關於基準設定檔
下一頁
為程式庫建立基準設定檔