配置基线配置文件生成

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

此页面介绍如何使用基线配置文件 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 插件配置中，如下所示，在 :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 将触发为每个发布程序集生成新的基线配置文件。这意味着运行组装发布构建任务（例如 ./gradlew:app:assembleRelease）也会触发 :app:generateReleaseBaselineProfile，启动基线配置文件检测测试，并在其运行的基线配置文件构建上构建。虽然自动生成帮助用户获得最佳性能优势，但由于双重构建和检测测试，它也会增加构建时间。

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

Kotlin

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

Groovy

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

在前面的示例中，任务 generateFreeReleaseBaselineProfile 在启动 assembleFreeRelease 时运行。当用户希望例如有一个用于分发的 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
        }
    }
}

过滤配置文件规则

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

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

代码实验室

深入研究宏基准测试以衡量性能。
了解更多
生成适合 Android 应用程序的自定义基线配置文件并验证其有效性。
了解更多
上一页
为库创建基线配置文件
下一页
使用 Macrobenchmark 库进行测量