Android NDK开发详解之调试和性能分析的配置基准配置文件生成

实验：虽然基准配置文件 Gradle 插件处于 Alpha 版阶段，但 DSL 可能仍会发生变化。如果您遇到 bug，请在问题跟踪器中报告这些 bug。
使用基准配置文件 Gradle 插件，可以更轻松地生成和维护基准配置文件。它可帮助您执行以下任务：

为您的应用创建新的基准配置文件。
为您的库创建新的基准配置文件。
自定义基准配置文件的生成。
本页介绍了如何使用基准配置文件 Gradle 插件自定义基准配置文件的生成。

插件要求

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

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

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

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 {
       create<com.android.build.api.dsl.ManagedVirtualDevice>("pixel6Api31") {
           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 任务。举个例子，当有两个变种（比如免费和付费变种）和一个发布 build 类型时，任务如下所示：

• generateFreeReleaseBaselineProfile
• generatePaidReleaseBaselineProfile
• generateReleaseBaselineProfile
  如需按变体指定合并行为，请使用以下代码：

Kotlin

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

Groovy

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

在上面的示例中，标志设为 true 的所有变体都会合并到 src/main/generated/baselineProfiles 中，而标志设为 false 的变体对应的配置文件会保留在文件夹 src//generated/baselineProfiles 中。

默认情况下，对于库，mergeIntoMain 设为 true；对于应用，则设为 false。

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

您可将基准配置文件配置为随每个发布 build 自动生成，而不是使用任务 generateBaselineProfile 手动生成。如果自动生成配置文件，则最新的配置文件会包含在发布 build 中。

如需为发布 build 启用自动生成功能，请使用 automaticallyGenerateDuringBuild 标志：

Kotlin

baselineProfile {
    automaticallyGenerateDuringBuild = true
}

Groovy

baselineProfile {
    automaticallyGenerateDuringBuild = true
}

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

注意：您可以随时显式运行基准配置文件生成操作，并使用 ./gradlew :app:generateReleaseBaseline :app:assembleRelease 组装发布 build，在这种情况下，基准配置文件先生成，然后与组装好的发布版本打包在一起。
您还可以按变体指定此行为，如以下示例所示：

Kotlin

baselineProfile {
    variants {
        freeRelease {
            automaticallyGenerateDuringBuild = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            automaticallyGenerateDuringBuild = true
        }
    }
}

在前面的示例中，generateFreeReleaseBaselineProfile 任务会在开始 assembleFreeRelease 时运行。这有时会很有帮助，比如在以下情况下：用户想有一个针对分发 build 的 release（始终会在构建时生成配置文件），和一个针对内部测试的 releaseWithoutProfile。

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

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

true：基准配置文件存储在 src//generated/baselineProfiles 中。这样，您就可以使用源目录提交最新生成的配置文件。
false：基准配置文件存储在 build 目录下的中间文件中。这样，您在提交代码时不会保存最新生成的配置文件。
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.**")
            }
        }
    }
}

注意：特定变体 (freeRelease) 的过滤器会添加到变种级 (free) 过滤器、build 级 (release) 过滤器以及在 variants 组成块之外指定的全局过滤器。
您还可以在 BaselineProfileRule.collect() 中使用 filterPredicate 参数来过滤规则，但我们建议您使用 Gradle 插件进行过滤，因为这种方法可让您更轻松地过滤子软件包以及在同一位置配置整个模块。

其他说明

创建基准配置文件时，还需要注意一些其他事项：

已编译的基准配置文件必须小于 1.5 MB。此规则不适用于源文件中的文本格式，源文件在编译之前通常会比 1.5 MB 大出很多。如需验证二进制基准配置文件的大小，请在输出工件中找到相应文件（APK：位于 assets/dexopt/baseline.prof 下；AAB：位于 BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof 下）。

提示：在 Android Studio Flamingo (2022.2.1) 或更高版本中，请从 APK 分析器中验证大小。
如果宽泛规则对应用编译过多，就会增加磁盘访问，进而降低启动速度。如果您刚开始使用基准配置文件，无需担心。不过，添加大量历程可能会导致性能不够理想，具体取决于您的应用以及历程的大小和数量。请尝试通过使用不同的配置文件和确认新增历程不会导致性能降低来测试性能。