114 lines
3.1 KiB
Markdown
114 lines
3.1 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 场景验收。
|
||
|
||
这样构建产物与上机验证保持分离，避免脚本意外操作设备。
|