# 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 场景验收。

这样构建产物与上机验证保持分离，避免脚本意外操作设备。