149 lines
7.5 KiB
Markdown
149 lines
7.5 KiB
Markdown
# Android Particle Validation APK Pipeline
|
||
|
||
这是 `MapLibreAndroidTestApp` 粒子验证 APK 的唯一推荐构建入口。
|
||
|
||
以后不要再手工回忆 Gradle 参数，也不要直接拿 `build/outputs` 目录中的旧 APK 做验证。
|
||
|
||
## 一键构建
|
||
|
||
在 Mac 的仓库根目录执行：
|
||
|
||
```bash
|
||
./tools/particle_android_validation/build_validation_apk.sh
|
||
```
|
||
|
||
Pipeline 固定执行：
|
||
|
||
```text
|
||
MapLibreAndroidTestApp
|
||
OpenGL Debug
|
||
ABI = x86_64
|
||
stripNativeDebugSymbols = true
|
||
```
|
||
|
||
对应 Gradle 核心参数为：
|
||
|
||
```text
|
||
:MapLibreAndroidTestApp:assembleOpenglDebug
|
||
-Pmaplibre.abis=x86_64
|
||
-Pmaplibre.validation.stripNativeDebugSymbols=true
|
||
--console=plain
|
||
```
|
||
|
||
## 稳定产物
|
||
|
||
成功后统一输出到：
|
||
|
||
```text
|
||
artifacts/maplibre-particle/android-validation/
|
||
├── MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
|
||
├── build-info.txt
|
||
└── build.log
|
||
```
|
||
|
||
`artifacts/maplibre-particle/` 已在 `.gitignore` 中，不进入 Git。
|
||
|
||
`build-info.txt` 会记录 commit、branch、dirty 状态、构建时间、ABI、APK 大小、`libmaplibre.so` 大小和 SHA-256。
|
||
|
||
## Pipeline 为什么必须存在
|
||
|
||
历史上有两个容易重复踩中的问题：
|
||
|
||
1. 少传 `-Pmaplibre.validation.stripNativeDebugSymbols=true` 时，Debug `libmaplibre.so` 会包含大量 native debug symbols，APK 可膨胀到数百 MB。
|
||
2. 在同一路径先生成超大 APK、再切换 strip 参数增量打包时，APK 文件可能保留旧 ZIP 尾部数据，出现约 95 MB 的物理文件；因此 Pipeline 在每次构建前都会先删除最终 APK，只重新 package，不执行全量 Gradle clean。
|
||
|
||
STEP-090/091 的正常 x86_64 Validation APK 基线约为 57 MB。
|
||
|
||
## 自动环境处理
|
||
|
||
Pipeline 会优先使用已有 `JAVA_HOME` / `ANDROID_HOME`。
|
||
|
||
若未设置，会在当前 Mac 上自动尝试：
|
||
|
||
```text
|
||
Java 17:
|
||
/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
|
||
/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
|
||
/usr/libexec/java_home -v 17
|
||
|
||
Android SDK:
|
||
~/Library/Android/sdk
|
||
```
|
||
|
||
Java 不是 17、Android SDK 不存在或 Gradle 失败时直接停止，不会把旧 APK 当成成功产物。
|
||
|
||
## 构建后自动验收
|
||
|
||
Pipeline 会检查：
|
||
|
||
- APK ZIP 完整性；
|
||
- native ABI 必须只有 `x86_64`；
|
||
- 必须存在 `lib/x86_64/libmaplibre.so`；
|
||
- `libmaplibre.so` 默认不得超过 80 MiB；
|
||
- APK 默认不得超过 100 MiB；
|
||
- 生成 SHA-256；
|
||
- 保存完整 Gradle 日志。
|
||
|
||
超过体积门槛默认视为 pipeline 失败，以防再次交付未 strip 或带旧 ZIP 尾部的 APK。
|
||
|
||
如未来 Validation App 因真实资源增长需要调整门槛，可显式覆盖：
|
||
|
||
```bash
|
||
MAPLIBRE_VALIDATION_MAX_APK_BYTES=134217728 \
|
||
MAPLIBRE_VALIDATION_MAX_LIBMAPLIBRE_BYTES=94371840 \
|
||
./tools/particle_android_validation/build_validation_apk.sh
|
||
```
|
||
|
||
也可以修改产物目录：
|
||
|
||
```bash
|
||
MAPLIBRE_VALIDATION_OUT_DIR=/tmp/my-validation \
|
||
./tools/particle_android_validation/build_validation_apk.sh
|
||
```
|
||
|
||
## 边界
|
||
|
||
这个 Pipeline 只负责**制作和验收 APK**，不自动执行：
|
||
|
||
- ADB 安装；
|
||
- 启动 Activity；
|
||
- 真机/模拟器交互；
|
||
- STEP 场景验收。
|
||
|
||
这样构建产物与上机验证保持分离，避免脚本意外操作设备。
|
||
|
||
## STEP-113 原 PBF 专用 Test App Fast Path 复测
|
||
|
||
本测试不使用 STEP-114 的简化 FAST_SMOKE。保留原 Step113PbfGateScene 的 PBF URL、63 个正式基础层与 Native 真实计数。STEP-116 仅对 STATIC_RC 的空 SDK Annotation 辅助层做一次移除及生命周期保护，并增加诊断；其余四场景不做此调整。需要用户在 RDC 独立审计并锁定源码后手工完成标准 APK 编译和安装。工具检查 tracked clean、build-info Git commit 与 HEAD、APK SHA、设备安装 SHA；不一致即拒绝。原 STEP-110/111 等未跟踪任务书可以保留。
|
||
|
||
在 Mac 的 MapLibreParticleLab 根目录依序执行：
|
||
|
||
./tools/particle_android_validation/build_validation_apk.sh
|
||
|
||
/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 install -r artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
|
||
|
||
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --preflight-only
|
||
|
||
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario STATIC_RC --seconds 75
|
||
|
||
前两项为用户手工 Android 构建和更新安装，不得在未授权情况下代劳。后两项由 RDC 或用户执行。脚本使用明确 ADB serial 启动原有 Activity 的 STEP-113 原场景，按当前 PID 还原 STEP113Gate 的 Base64 Logcat summary，计算实际 Fast/Full 计数差及 R Build/Reuse，保存到忽略 Git 的 artifacts/maplibre-particle/android-validation/step113-retest-时间/场景/ 目录。
|
||
|
||
FAST_OBSERVED 仅表示实际 Fast 数字增长，不代表像素等价、性能或所有安全回退已验收；NO_FAST_OBSERVED 表示仍未进入，记录完整 R fallback 和 24 Gate 聚合。STALE_APK / INSUFFICIENT_SAMPLES 不是 PASS。依次需要时用 --scenario PBF63、PARTICLE_OFF、PARTIAL_RCRR、SOURCE_CHANGE。SOURCE_CHANGE 的手动 Source mutation 仍须通过 App 原菜单做独立验证，脚本不会自行修改 Source。阶段事实详见 docs/50_Step记录/STEP-115_STEP113原PBF专用App复测准备_v1.md。
|
||
|
||
## STEP-116 当前交接
|
||
|
||
本轮只交源码，缺 `tide` 与 Symbol R 缓存准入继续 fail-closed，不能宣称原 STATIC_RC 已出现 Fast。Native AnnotationManager 在后续真实 Symbol Annotation add/update 与 Style loaded 时同步恢复缺失 points；Test App stop 重加原空层，后续 Annotation/Style 变化撤销空层验收条件，不周期删除新内容。原63层和Source定义保留，内部Annotation Source不删除；源码预期STATIC_RC由66层变65层，须以最新设备manifest核验。
|
||
|
||
复测脚本现要求至少75秒，在PID出现后等待完整请求时长；建议 `--scenario STATIC_RC --seconds 90`。同generation/lifecycle、plan/base parity、24Gate、mismatch0、计数单调及blocked撤销均为必要条件。summary新增缺源ID/Placement/commands/Source表；120帧仍需用户手动导出。精确命令、用户一次手工build/install、RDC Native定向测试及阴性结果解释见 [STEP-116 专用APP验收](../../docs/60_测试/STEP-116_STEP113原PBF专用APP验收_v1.md)。历史STEP115记录保留为当时事实，不代表本轮设备已验收。
|
||
|
||
## STEP-118 用户批准排除 tide 的独立实验
|
||
|
||
2026-10-11 用户明确允许删除 tide。正式PBF的 sources 中本就不存在 tide；唯一引用它的是原63基础层中的 tide-spots（Symbol）。只运行removeSource并不能移除这个依赖。新增独立 STATIC_RC_NO_TIDE 实验场景，在 TestApp 的临时Style副本中**只移除这一条孤立Layer**，原五场景、远端PBF Style和Native24 Gate不变。原生产63层及fingerprint完整保留在Parity数据中，派生场景明确标为基础62层（加两天气层总64，SDK空Annotation移除），不允许冒充原63层生产验收。
|
||
|
||
派生场景在读取原Style时严格断言当前tide Source不存在、唯一引用层是Symbol tide-spots，否则BLOCKED。旧场景验收器仍检查basePreserved=true；新场景验收器独立要求原63/有效62/总64、唯一排除tide-spots/tide、R[0,62)、Annotation Source保留、24 Gate、SHA同版本约束、真实Native增量。源缺失被解除不代表Symbol Placement、Cache Build或Fast已经成功。
|
||
|
||
启动命令：
|
||
python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario STATIC_RC_NO_TIDE --seconds 90
|
||
|
||
完整步骤见 docs/60_测试/STEP-118_tide移除Android实机验收_v1.md。
|