配置基准配置文件生成

Baseline Profile Gradle 插件可让您更轻松地生成和维护基准配置文件。它可帮助您完成以下任务

本页面介绍了如何使用 Baseline Profile 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 添加到 Baseline Profile Gradle 插件配置中，以使用 GMD 生成基准配置文件，即在 :baselineprofile 测试模块的 build.gradle.kts 中进行配置

Kotlin

baselineProfile {
    managedDevices += "pixel6Api31"
}

Groovy

baselineProfile {
    managedDevices = ['pixel6Api31']
}

当您使用 GMD 生成基准配置文件时，请在 :baselineprofile 测试模块中将 useConnectedDevices 设置为 false

Kotlin

baselineProfile {
    ...
    useConnectedDevices = false
}

Groovy

baselineProfile {
    ...
    useConnectedDevices false
}

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

您可以按变体、按产品风味生成基准配置文件，也可以生成一个单独的文件以供所有变体使用。如以下示例所示，通过合并设置来控制此行为，即在应用或库模块的 build.gradle.kts 中进行配置。

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，应用的 false。

在新版本发布时自动生成基准配置文件

您可以配置基准配置文件以在每次发布构建时自动生成，而不是手动使用 generateBaselineProfile 任务。通过自动生成，最新更新的配置文件会包含在发布构建中。

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

Kotlin

baselineProfile {
    automaticGenerationDuringBuild = true
}

Groovy

baselineProfile {
    automaticGenerationDuringBuild true
}

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

您也可以针对每个变体指定此行为，如以下示例所示

Kotlin

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

Groovy

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

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

将基准配置文件存储到源中

您可以通过应用或库模块的 build.gradle.kts 中的 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
        }
    }
}

停用警告

默认情况下，Baseline Profile Gradle 插件会就可能导致问题的情况向您发出警告。要停用警告，您可以在 build.gradle.kts 文件中将相关选项设置为 false。以下是警告选项

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

过滤配置文件规则

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

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

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

Baseline Profile 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。这不适用于源文件中的文本格式，这些文本格式在编译前通常要大得多。通过在输出工件中查找 APK 的 assets/dexopt/baseline.prof 或 AAB 的 BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof 来验证二进制基准配置文件的大小。

  • 编译过多应用程序的广泛规则可能会因磁盘访问增加而降低启动速度。如果您刚开始使用基准配置文件，请不要担心这一点。但是，根据您的应用以及 journey 的大小和数量，添加大量 journey 可能会导致次优性能。通过尝试不同的配置文件并验证添加后性能没有下降来测试您应用的性能。

Codelabs

深入了解宏基准测试以衡量性能。
了解详情
生成针对 Android 应用量身定制的自定义基准配置文件，并验证其有效性。
了解详情
上一页
为库创建基准配置文件
下一页
使用宏基准测试库进行衡量