配置基线配置文件生成

基线配置文件 Gradle 插件使生成和维护基线配置文件变得更加容易。它可以帮助您完成以下任务

本页介绍如何使用基线配置文件 Gradle 插件自定义您的基线配置文件生成。

插件要求

AGP 8.0 或更高版本
依赖于最新 Gradle 插件版本

使用 Gradle 管理的设备生成基线配置文件

要使用 Gradle 管理的设备 (GMD) 生成您的基线配置文件，请在配置文件生产者模块（可能是 :baselineprofile 测试模块）的 build.gradle.kts 配置中添加一个，如以下示例所示

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

通过将 GMD 添加到基线配置文件 Gradle 插件配置中，使用 GMD 生成基线配置文件，如下所示

Kotlin

baselineProfile {
    managedDevices += "pixel6Api31"
}

Groovy

baselineProfile {
    managedDevices = ['pixel6Api31']
}

当您使用 GMD 生成基线配置文件时，请将 useConnectedDevices 设置为 false

Kotlin

baselineProfile {
    ...
    useConnectedDevices = false
}

Groovy

baselineProfile {
    ...
    useConnectedDevices false
}

为不同的变体生成基线配置文件

您可以为每个变体、每个风味或作为单个文件生成基线配置文件，以便用于所有变体。通过合并设置控制此行为，如以下示例所示。

Kotlin

baselineProfile {
    mergeIntoMain = true
}

Groovy

baselineProfile {
    mergeIntoMain true
}

要将所有变体的生成配置文件合并到单个配置文件中，请将 mergeIntoMain 设置为 true。当此设置为 true 时，无法生成每个变体的基线配置文件，因此只有一个名为 generateBaselineProfile 的 Gradle 任务。配置文件输出在 src/main/generated/baselineProfiles 中。

要禁用合并并为每个变体生成一个配置文件，请将 mergeIntoMain 设置为 false。在这种情况下，存在多个特定于变体的 Gradle 任务。例如，当存在两个风味（例如免费版和付费版）和一个发布构建类型时，任务如下

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

要指定每个变体的合并行为，请使用以下代码

Kotlin

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

Groovy

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

在前面的示例中，将标志设置为 true 的所有变体都合并到 src/main/generated/baselineProfiles 中，而将标志设置为 false 的变体的配置文件保留在文件夹 src/<variant>/generated/baselineProfiles 中。

默认情况下，库的 mergeIntoMain 设置为 true，应用程序的 mergeIntoMain 设置为 false。

在组装新版本时自动生成基线配置文件

您可以配置基线配置文件，使其在每次发布构建时自动生成，而不是手动使用任务 generateBaselineProfile。使用自动生成，最新的配置文件将包含在发布版本中。

要为发布版本启用自动生成，请使用 automaticGenerationDuringBuild 标志

Kotlin

baselineProfile {
    automaticGenerationDuringBuild = true
}

Groovy

baselineProfile {
    automaticGenerationDuringBuild true
}

将 automaticGenerationDuringBuild 标志设置为 true 会触发为每个发布程序集生成新的基线配置文件。这意味着运行程序集发布构建任务，例如 ./gradlew:app:assembleRelease，也会触发 :app:generateReleaseBaselineProfile，启动基线配置文件检测测试，并构建在其中运行基线配置文件构建。虽然自动生成有助于用户获得最佳性能优势，但由于双重构建和检测测试，它也会增加构建时间。

您还可以像以下示例所示，为每个变体指定此行为

Kotlin

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

Groovy

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

在前面的示例中，任务 generateFreeReleaseBaselineProfile 在启动 assembleFreeRelease 时运行。当用户希望在构建时始终生成配置文件的 release 分发构建，以及用于内部测试的 releaseWithoutProfile 构建时，这很有帮助。

将基线配置文件存储到源代码中

您可以通过 saveInSrc 标志将基线配置文件存储在源代码目录中

true：基线配置文件存储在 src/<variant>/generated/baselineProfiles 中。这使您可以将最新的生成配置文件与源代码一起提交。
false：基线配置文件存储在构建目录中的中间文件中。这样，在提交代码时，您不会保存最新的生成配置文件。

Kotlin

baselineProfile {
    saveInSrc = true
}

Groovy

baselineProfile {
    saveInSrc true
}

您还可以为每个变体指定此行为

Kotlin

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

Groovy

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

筛选配置文件规则

基线配置文件 Gradle 插件允许您筛选生成的基线配置文件规则。这对于库来说尤其有用，如果您想排除针对属于示例应用程序或库本身的其他依赖项的类和方法的配置文件规则。过滤器可以包含和排除特定包和类。当您只指定排除项时，只会排除匹配的基线配置文件规则，其他所有规则都会包含。

过滤器规范可以是以下任何一项

包名称以双通配符结尾，以匹配指定的包和所有子包。例如，com.example.** 匹配 com.example.method 和 com.example.method.bar。
包名称以通配符结尾，以匹配指定的包。例如，com.example.* 匹配 com.example.method 但不匹配 com.example.method.bar。
类名称以匹配特定类，例如 com.example.MyClass。

以下示例展示了如何包含和排除特定包

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

如下所示，为不同的变体自定义筛选规则

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

您也可以使用 filterPredicate 参数在 BaselineProfileRule.collect() 中筛选规则，但我们建议使用 Gradle 插件进行筛选，因为它提供了一种更简单的子包筛选方法，以及一个配置整个模块的单一位置。

自定义基准测试和基线配置文件构建类型

基线配置文件 Gradle 插件创建其他构建类型以生成配置文件并运行基准测试。这些构建类型以 benchmark 和 nonMinified 为前缀。例如，对于 release 构建类型，插件会创建 benchmarkRelease 和 nonMinifiedRelease 构建类型。这些构建类型会自动配置为特定用例，通常不需要任何自定义。但是，在某些情况下，可能仍然需要应用一些自定义选项，例如，应用不同的签名配置。

您可以使用构建类型属性的子集来自定义自动生成的构建类型；不可用的属性将被覆盖。以下示例展示了如何自定义其他构建类型以及哪些属性被覆盖

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

其他说明

在创建基线配置文件时，请注意以下事项

编译后的基线配置文件的大小必须小于 1.5 MB。这并不适用于源文件中的文本格式，这些文本格式在编译之前通常要大得多。通过在输出工件下的 assets/dexopt/baseline.prof（对于 APK）或 BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof（对于 AAB）中找到二进制基线配置文件，验证其大小。

提示： 在 Android Studio Flamingo（2022.2.1）或更高版本中，在 APK 分析器中验证大小。
编译太多应用程序的宽泛规则会导致磁盘访问增加，从而降低启动速度。如果您只是刚开始使用基线配置文件，请不要担心这一点。但是，根据您的应用程序以及行程的大小和数量，添加大量行程可能会导致性能不佳。通过尝试不同的配置文件并验证添加行程后性能没有下降，测试应用程序的性能。

Codelabs

使用 Macrobenchmark 检查应用程序性能

深入了解宏基准测试以衡量性能。

了解更多

使用基线配置文件提高应用程序性能

生成针对 Android 应用程序定制的基线配置文件，并验证其有效性。

了解更多

为库创建基线配置文件

使用 Macrobenchmark 库进行测量