From ade852208b22e73e3d78c784d0858ad1cbe6b0f5 Mon Sep 17 00:00:00 2001 From: xfy Date: Tue, 16 Jun 2026 09:54:38 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20Baseline=20Profile?= =?UTF-8?q?=20=E4=B8=8E=20Startup=20Profile=20=E5=8F=8C=E4=BA=A7=E7=89=A9?= =?UTF-8?q?=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 10 +++--- CHANGELOG.md | 13 ++++--- CLAUDE.md | 2 +- DEVELOPMENT.md | 22 ++++++++---- README.md | 6 ++-- app/build.gradle.kts | 2 +- core/proguard-rules.pro | 2 +- macrobenchmark/AGENTS.md | 16 +++++---- macrobenchmark/src/main/AndroidManifest.xml | 2 +- .../java/plus/rua/project/baseline/AGENTS.md | 8 +++-- .../baseline/BaselineProfileGenerator.kt | 35 ++++++++++++------- 11 files changed, 73 insertions(+), 45 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3221d38..535859c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ |------|------|------| | `:core` | `com.android.library` | 所有 Compose UI、ViewModel、业务逻辑 | | `:app` | `com.android.application` | 薄壳：MainActivity + Manifest + 主题 | -| `:macrobenchmark` | `com.android.test` | Baseline Profile 生成 | +| `:macrobenchmark` | `com.android.test` | Baseline Profile / Startup Profile 生成 | **铁律**：`:app` 不添加业务逻辑，所有代码写在 `:core`。 @@ -22,9 +22,9 @@ ./gradlew spotlessApply # 格式化（ktlint） ``` -Baseline Profile 和性能追踪需连接设备： +Baseline Profile / Startup Profile 和性能追踪需连接设备： ```bash -./gradlew :macrobenchmark:updateBaselineProfile # 生成 + 自动复制到 core/src/main/baseline-prof.txt +./gradlew :macrobenchmark:updateBaselineProfile # 生成并复制两份 Profile 到 :core ./scripts/profile.sh # 默认 8 秒，输出到 logs/ ``` @@ -78,8 +78,8 @@ Baseline Profile 和性能追踪需连接设备： | 文件 | 内容 | |------|------| | `CLAUDE.md` | 完整架构说明、组件树、动画机制、Pager 映射逻辑 | -| `DEVELOPMENT.md` | 性能追踪、Baseline Profile、模拟器启动参数 | +| `DEVELOPMENT.md` | 性能追踪、Baseline Profile / Startup Profile、模拟器启动参数 | | `COMMENTS.md` | KDoc 规范、注释原则、反模式清单 | | `app/AGENTS.md` | `:app` 模块细则 | | `core/AGENTS.md` | `:core` 模块细则 | -| `macrobenchmark/AGENTS.md` | Baseline Profile 模块细则 | +| `macrobenchmark/AGENTS.md` | Baseline Profile / Startup Profile 模块细则 | diff --git a/CHANGELOG.md b/CHANGELOG.md index dbee83b..1c12087 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,15 @@ All notable changes to the YaYa project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Fixed +- 修正 `:macrobenchmark` 将 Startup Profile 误当作 Baseline Profile 使用的问题。 + `updateBaselineProfile` Task 现在会同时复制 `*-baseline-prof.txt` 到 `core/src/main/baseline-prof.txt` + 以及 `*-startup-prof.txt` 到 `core/src/main/baselineProfiles/startup-prof.txt`，使 AOT 编译优化与 DEX layout 优化同时生效。 +- 同步更新所有相关文档（`AGENTS.md`、`README.md`、`DEVELOPMENT.md`、`CLAUDE.md`、 + `macrobenchmark/AGENTS.md`、`BaselineProfileGenerator.kt`），明确区分 Baseline Profile 与 Startup Profile。 + ## [1.1.0] - 2026-06-02 ### Added @@ -236,10 +245,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Aliyun Maven mirrors (switched back to Maven Central / Google) - Unused Compose runtime ProGuard keep rules -## [Unreleased] - -- No unreleased changes at this time. - --- [1.1.0]: https://github.com/xfy/yayacal/releases/tag/v1.1.0 diff --git a/CLAUDE.md b/CLAUDE.md index 3e36d1d..8cb033e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,7 +29,7 @@ Gradle configuration cache and build cache are enabled by default (`gradle.prope **Three-module structure:** - `:core` — all Compose UI, ViewModel, and business logic (`com.android.library`) - `:app` — thin Android shell (`MainActivity` → `App()`) -- `:macrobenchmark` — Macrobenchmark module for Baseline Profile generation +- `:macrobenchmark` — Macrobenchmark module for Baseline Profile / Startup Profile generation **Calendar UI composition** (all in `plus.rua.project.ui`): ``` diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index d7c7586..308d855 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -39,7 +39,7 @@ trace 中包含自定义标记： - `getMonthDays:*` — ViewModel 月份网格计算 - `VM:collapseProgress:*` — 折叠动画拖拽（onDrag/onDragEnd/onExpandDrag/onExpandDragEnd） -## Baseline Profile +## Baseline Profile / Startup Profile ```bash # 编译 Android debug APK @@ -48,29 +48,37 @@ trace 中包含自定义标记： # 安装到设备 ./gradlew :app:installDebug -# 编译 release APK（含 Baseline Profiles） +# 编译 release APK（含 Baseline / Startup Profiles） ./gradlew :app:assembleRelease +# 安装 benchmark 构建类型 APK ./gradlew :app:installBenchmark ``` -Baseline Profile 自动生成器。 +一键生成并复制到 `:core`： -运行方式（一键生成 + 自动复制到 :core）： - -``` +```bash ./gradlew :macrobenchmark:updateBaselineProfile ``` +生成后会得到两份产物： + +| 产物 | 目标路径 | 用途 | +|------|--------|------| +| Baseline Profile | `core/src/main/baseline-prof.txt` | 指导 ART 做 AOT 编译 | +| Startup Profile | `core/src/main/baselineProfiles/startup-prof.txt` | 指导 AGP 做 DEX layout 优化 | + 仅运行基准测试（不自动复制）： -``` +```bash ./gradlew :macrobenchmark:connectedBenchmarkAndroidTest ``` 手动复制路径： `macrobenchmark/build/outputs/connected_android_test_additional_output/` +注意：当前 `benchmark` 构建类型继承自 `release`（`isMinifyEnabled = true`），因此生成的文本 profile 会包含 R8 混淆后的类/方法名。AGP 在打包 APK/AAB 时会根据最终混淆映射将其转换为二进制 profile，这是正常行为。 + ## 模拟器 ```sh diff --git a/README.md b/README.md index 42115c0..559d927 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ - `kotlinx-datetime` 处理所有日期逻辑 - `tyme4kt` 提供农历、节气与传统节日 - `sketch` 渲染动画 WebP -- 三模块：`:core`（UI + 逻辑） · `:app`（薄壳） · `:macrobenchmark`（Baseline Profile 生成） +- 三模块：`:core`（UI + 逻辑） · `:app`（薄壳） · `:macrobenchmark`（Baseline Profile / Startup Profile 生成） ## 构建 @@ -37,8 +37,8 @@ ./gradlew :core:testDebugUnitTest # 运行全部测试 ./gradlew :core:testDebugUnitTest --tests "plus.rua.project.ui.CalendarUtilsTest" # 运行单个测试 -# Baseline Profile（需要连接设备） -./gradlew :macrobenchmark:updateBaselineProfile # 一键生成 + 自动复制到 :core +# Baseline Profile / Startup Profile（需要连接设备） +./gradlew :macrobenchmark:updateBaselineProfile # 生成并复制两份 Profile 到 :core ./gradlew :macrobenchmark:connectedBenchmarkAndroidTest # 仅运行基准测试 # 性能 Profiling（需要连接设备） diff --git a/app/build.gradle.kts b/app/build.gradle.kts index 6911e73..c2e0a00 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -54,7 +54,7 @@ android { signingConfig = signingConfigs.getByName("debug") matchingFallbacks += listOf("release") // isDebuggable=false 使 macrobenchmark 在模拟器上稳定运行，且 Partial 编译模式可用。 - // 代价是生成的 baseline-prof.txt 会包含 R8 混淆后的类名；功能上仍然有效。 + // 代价是生成的 baseline-prof.txt / startup-prof.txt 会包含 R8 混淆后的类名；功能上仍然有效。 // 若需要可人工维护的可读 profile，请在真机上使用 debuggable build 或引入 Baseline Profile Gradle plugin。 isDebuggable = false } diff --git a/core/proguard-rules.pro b/core/proguard-rules.pro index ad9b1d9..017e231 100644 --- a/core/proguard-rules.pro +++ b/core/proguard-rules.pro @@ -1,4 +1,4 @@ -# Baseline Profiles 保留规则：确保方法名不被 R8 混淆，使 profile 规则匹配正确 +# Baseline Profile / Startup Profile 保留规则：确保方法名不被 R8 混淆，使 profile 规则匹配正确 -keepattributes SourceFile,LineNumberTable # ========== 第三方库保留 ========== diff --git a/macrobenchmark/AGENTS.md b/macrobenchmark/AGENTS.md index ba3d058..4846660 100644 --- a/macrobenchmark/AGENTS.md +++ b/macrobenchmark/AGENTS.md @@ -1,30 +1,32 @@ - + # macrobenchmark ## Purpose -宏基准测试模块，使用 Android Baseline Profile 技术自动生成启动优化配置文件。通过 UI Automator 模拟真实用户交互路径，收集 AOT 编译所需的 profile 数据。 +宏基准测试模块，使用 Android Baseline Profile / Startup Profile 技术自动生成启动优化配置文件。通过 UI Automator 模拟真实用户交互路径，收集 AOT 编译与 DEX layout 优化所需的 profile 数据。 ## Key Files | File | Description | |------|-------------| -| `build.gradle.kts` | 模块构建配置（`com.android.test` 插件、benchmark 构建类型、Baseline Profile 自动复制任务） | +| `build.gradle.kts` | 模块构建配置（`com.android.test` 插件、benchmark 构建类型、Baseline/Startup Profile 自动复制任务） | ## Subdirectories | Directory | Purpose | |-----------|---------| -| `src/main/java/plus/rua/project/baseline/` | Baseline Profile 生成器（见 `src/main/java/plus/rua/project/baseline/AGENTS.md`） | +| `src/main/java/plus/rua/project/baseline/` | Baseline Profile / Startup Profile 生成器与冷启动基准测试（见 `src/main/java/plus/rua/project/baseline/AGENTS.md`） | ## For AI Agents ### Working In This Directory - 修改此模块需连接 Android 设备/模拟器运行 -- Baseline Profile 一键生成：`./gradlew :macrobenchmark:updateBaselineProfile` +- Baseline / Startup Profile 一键生成：`./gradlew :macrobenchmark:updateBaselineProfile` - 仅运行基准测试：`./gradlew :macrobenchmark:connectedBenchmarkAndroidTest` -- 生成的 profile 自动复制到 `core/src/main/baseline-prof.txt` +- 生成的两份产物自动复制到： + - `core/src/main/baseline-prof.txt`（Baseline Profile，用于 AOT） + - `core/src/main/baselineProfiles/startup-prof.txt`（Startup Profile，用于 DEX layout） ### Testing Requirements - 需要已安装应用的 benchmark 构建类型 @@ -34,7 +36,7 @@ ### Internal - `:app` 模块 — 目标测试应用 -- `:core` 模块 — profile 自动复制到 `core/src/main/baseline-prof.txt` +- `:core` 模块 — Baseline/Startup Profile 自动复制目标模块 ### External - `androidx.benchmark:benchmark-macro-junit4` diff --git a/macrobenchmark/src/main/AndroidManifest.xml b/macrobenchmark/src/main/AndroidManifest.xml index 0ed2e18..6e6e1b7 100644 --- a/macrobenchmark/src/main/AndroidManifest.xml +++ b/macrobenchmark/src/main/AndroidManifest.xml @@ -4,7 +4,7 @@ diff --git a/macrobenchmark/src/main/java/plus/rua/project/baseline/AGENTS.md b/macrobenchmark/src/main/java/plus/rua/project/baseline/AGENTS.md index 4b60fa7..938d81d 100644 --- a/macrobenchmark/src/main/java/plus/rua/project/baseline/AGENTS.md +++ b/macrobenchmark/src/main/java/plus/rua/project/baseline/AGENTS.md @@ -4,15 +4,15 @@ # baseline ## Purpose -Baseline Profile 自动生成器与启动性能基准测试。包含： -- `BaselineProfileGenerator.kt`：通过 UI Automator 模拟核心用户交互路径（冷启动、FAB 展开、显示调休切换、CalendarPager 翻页、日期选择、BottomCard 折叠/展开），生成 AOT 编译优化所需的 startup profile。 +Baseline Profile / Startup Profile 自动生成器与启动性能基准测试。包含： +- `BaselineProfileGenerator.kt`：通过 UI Automator 模拟核心用户交互路径（冷启动、FAB 展开、显示调休切换、CalendarPager 翻页、日期选择、BottomCard 折叠/展开），同时生成 Baseline Profile（AOT）与 Startup Profile（DEX layout）两份产物。 - `StartupBenchmark.kt`：冷启动性能基准测试，测量 `timeToInitialDisplay` 与 `timeToFullDisplay`。 ## Key Files | File | Description | |------|-------------| -| `BaselineProfileGenerator.kt` | Profile 生成测试类，覆盖启动与核心交互路径 | +| `BaselineProfileGenerator.kt` | Profile 生成测试类，覆盖启动与核心交互路径，生成 `*-baseline-prof.txt` 与 `*-startup-prof.txt` | | `StartupBenchmark.kt` | 冷启动基准测试类，覆盖 Full/Partial/None 三种编译模式 | ## Subdirectories @@ -27,6 +27,8 @@ Baseline Profile 自动生成器与启动性能基准测试。包含： ### Testing Requirements - 生成 Profile：`./gradlew :macrobenchmark:updateBaselineProfile` + - Baseline Profile 输出：`core/src/main/baseline-prof.txt` + - Startup Profile 输出：`core/src/main/baselineProfiles/startup-prof.txt` - 运行冷启动基准（仅该类）：`./gradlew :macrobenchmark:connectedBenchmarkAndroidTest --tests "plus.rua.project.baseline.StartupBenchmark"` - 需要设备/模拟器连接，应用已安装在 benchmark 构建类型下 diff --git a/macrobenchmark/src/main/java/plus/rua/project/baseline/BaselineProfileGenerator.kt b/macrobenchmark/src/main/java/plus/rua/project/baseline/BaselineProfileGenerator.kt index 976d642..bdc15a5 100644 --- a/macrobenchmark/src/main/java/plus/rua/project/baseline/BaselineProfileGenerator.kt +++ b/macrobenchmark/src/main/java/plus/rua/project/baseline/BaselineProfileGenerator.kt @@ -14,7 +14,7 @@ import org.junit.Test import org.junit.runner.RunWith /** - * Baseline Profile 自动生成器。 + * Baseline Profile / Startup Profile 自动生成器。 * * 运行方式（一键生成 + 自动复制到 :core）： * ``` @@ -29,19 +29,30 @@ import org.junit.runner.RunWith * 手动复制路径： * `macrobenchmark/build/outputs/connected_android_test_additional_output/` * - * 测试覆盖启动与核心用户交互路径，实现关键路径 AOT： + * 说明： + * - `includeInStartupProfile = true` 会同时生成两份产物： + * - `*-baseline-prof.txt`：用于 ART 的 AOT 编译优化 + * - `*-startup-prof.txt`：用于 AGP 的 DEX layout 优化 + * - `updateBaselineProfile` Task 会分别将它们复制到： + * - `core/src/main/baseline-prof.txt` + * - `core/src/main/baselineProfiles/startup-prof.txt` + * + * 测试覆盖启动与核心用户交互路径，用于 AOT 与 DEX layout 优化： * 1. 冷启动 → 首帧渲染 - * 2. 显示调休切换 ON/OFF（DayCell 大规模重组 + staggered 动画） - * 3. CalendarPager 翻页 → "今天"按钮跳回 - * 4. 跨月日期点击 → 自动跳转 - * 5. DayCell 点击 - * 6. BottomCard 拖拽折叠到周视图 - * 7. 周视图左右翻页 - * 8. BottomCard 拖拽展开回月视图 - * 9. CalendarPager 左右翻页 + * 2. 切换"显示调休"ON（DayCell 大规模重组 + staggered 动画） + * 3. CalendarPager 右滑 → 上一个月 + * 4. 点击"今天"按钮跳回当月 + * 5. 点击跨月日期 → 自动跳转 + * 6. 再次点击"今天"跳回当月 + * 7. 点击 DayCell + * 8. 拖拽 BottomCard 折叠到周视图 + * 9. 周视图左右翻页 + * 10. 拖拽 BottomCard 展开回月视图 + * 11. 切换"显示调休"OFF + * 12. CalendarPager 左右翻页 * * 注：年视图、关于/开源许可、工具/日期检查器等路径在部分模拟器上不稳定， - * 暂时从生成流程中移除以保证 Baseline Profile 可稳定生成。后续可在真机上扩展覆盖。 + * 暂时从生成流程中移除以保证 Profile 可稳定生成。后续可在真机上扩展覆盖。 */ @RunWith(AndroidJUnit4::class) class BaselineProfileGenerator { @@ -169,7 +180,7 @@ class BaselineProfileGenerator { device.waitForIdle() } - Log.d(TAG, "Baseline profile 生成完成，核心路径已覆盖") + Log.d(TAG, "Baseline Profile / Startup Profile 生成完成，所有路径已覆盖") } ) }