67 lines
5.0 KiB
Markdown
67 lines
5.0 KiB
Markdown
# STEP-080 — Android AAR 与 RN Test Host 标准构建流水线 v1
|
||
|
||
状态：完成
|
||
|
||
日期：2026-09-13
|
||
|
||
## 目标与基线
|
||
|
||
- 开始 HEAD / `origin/particle/main`：`d490578b973508d267c590dd604b033507c9b859`。
|
||
- 固定交付版本：RN package / Native AAR 均为 `13.4.1-particle.3`，Maven coordinate 为 `cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.3`。
|
||
- 任务开始前已有 Native `VERSION` 升级、JNI 头文件修正、STEP-062 文档 dirty、历史 untracked task/build/cache/tgz 和 Test Host generated Android/Expo/modules；均未清理、暂存或提交。
|
||
|
||
## 必做项
|
||
|
||
- [x] 新增 Linux producer `tools/particle_android_pipeline/linux_build_publish.sh`：报告 HEAD/branch/dirty；版本完全相等校验；SDK 解析；OpenGL Release 四 ABI 完整构建与 Maven Local publish；Maven artifact、旧 `.2` 保护、AAR/tgz bytes/SHA-256 校验；版本隔离 bundle/manifest。
|
||
- [x] Linux 所有 noisy native build、Gradle publish、RN TypeScript typecheck 与 npm pack 均强制经 build-output-throttle；runner 不可达即 fail-closed。
|
||
- [x] 默认 Linux 流程会生成可传输 AAR/POM/module/tgz 与 `artifacts/maplibre-particle/<version>/build-manifest.json`；目录已有 manifest 或不同 partial file 时 fail-closed，不覆盖历史 handoff。
|
||
- [x] 明确提供 `--reuse-existing`：仅能消费已完整存在的 Maven Local 发布物并在 manifest 标识 `PASS_REUSED_EXISTING_MAVEN_LOCAL`；不会冒充重新 AAR 构建。`--preflight` 无写入。
|
||
- [x] 新增 Windows consumer `tools/particle_android_pipeline/windows_build_testhost.ps1`：manifest 是唯一 artifact/version 输入，校验 SHA、安装 AAR/POM/module、同步 clean Test Host tracked source、固定 tgz 与 Maven coordinate、显式 prebuild/Debug APK build、输出 APK bytes/SHA-256。
|
||
- [x] Windows 默认不做安装、启动或 ADB；只有 `-Install` 与 `-Install -Run` 才使用固定设备 `192.168.1.146`。支持 `-DryRun`，先打印版本、AAR、tgz、Host、Maven Local 与 Gradle command。
|
||
- [x] 新增中文 README；版本升级必须先同步 `platform/android/VERSION` 与 RN `package.json`，pipeline 只校验，绝不暗改版本。
|
||
- [x] `.gitignore` 忽略 `/artifacts/maplibre-particle/`，生成 AAR/tgz/manifest 不进入 scoped commit。
|
||
|
||
## 允许修改
|
||
|
||
- `tools/particle_android_pipeline/` 的 Linux/Windows 脚本及说明。
|
||
- `.gitignore`、本 Step、完成报告与 `粒子开发记录.md`。
|
||
- 运行时写入 Git ignore 的 `local.properties`、`.codex-build-logs/`、`artifacts/`。
|
||
|
||
## 禁止修改
|
||
|
||
- Core、Renderer、QBIN、Binding、JNI 业务语义。
|
||
- Native/RN 版本值、既有 dirty/untracked、历史 Maven Local `.2` 发布物。
|
||
- Windows APK/ADB/设备、Jest、iOS/Metal；本 Step 不重复完整 Linux AAR 编译。
|
||
|
||
## 构建与验证
|
||
|
||
以下 Linux 验证均在 `particle-codex` tmux session 内完成：
|
||
|
||
- [x] `bash -n tools/particle_android_pipeline/linux_build_publish.sh`：PASS。
|
||
- [x] `linux_build_publish.sh --preflight`：PASS；SDK 解析为 `/root/Android/Sdk`，无 build/package/artifact 写入。
|
||
- [x] `linux_build_publish.sh --reuse-existing`：PASS；不运行完整 AAR build/publish，验证现存 `.3` Maven Local 的 AAR/POM/module，保护 `.2` 字节不变；经限流完成 RN package typecheck 与 npm pack。
|
||
- [x] manifest JSON contract：AAR/POM/module/tgz 的存在、绝对路径、bytes、SHA-256、版本和 Maven coordinate 全部 PASS。
|
||
- [x] tarball `package/package.json` version 与 Native `13.4.1-particle.3` 一致：PASS。
|
||
- [x] `git diff --check -- .gitignore`：PASS。
|
||
- [ ] Windows PowerShell parser/static validation：本 Linux 环境无 `pwsh`，明确 `POWERSHELL_PARSE_UNAVAILABLE_NO_PWSH`；未伪称 PASS。
|
||
|
||
## 当前结果
|
||
|
||
本轮 bundle 已在 Git ignore 路径生成：
|
||
|
||
```text
|
||
artifacts/maplibre-particle/13.4.1-particle.3/build-manifest.json
|
||
```
|
||
|
||
manifest 记录构建 HEAD、分支、dirty 状态、版本、四 ABI、OpenGL、Maven coordinate、AAR/POM/module/tgz 的 path/bytes/SHA-256 和 Linux validation result。验证使用的 existing AAR SHA-256 为 `9ef03eb0d0c03457adc04847cfa69fb67d85191daecd64d3b76db2ad8cc688cd`，tgz SHA-256 为 `6c8af6ff19adb4e25785b54bea3edd1dc7d0502d9158cf1c519d84b69d08ee55`。
|
||
|
||
## 未完成与阻塞
|
||
|
||
- 未重复执行完整四 ABI AAR 构建与 Maven Local publish：任务明确禁止为验证重复完整 AAR 编译；默认脚本已固化该受限命令，验证仅复用现存完整 `.3` publication。
|
||
- Linux 无 `pwsh`，因此未能本机解析 Windows PowerShell。Windows `-DryRun`、npm/prebuild/Gradle APK、安装、启动和设备验收均未执行，须在 Windows 11 使用该 manifest 完成；这不是 Linux 流水线实现阻塞。
|
||
- Jest、Windows APK/ADB/设备、iOS/Metal 均未执行。
|
||
|
||
## 下一步
|
||
|
||
Windows 11 将完整 Linux bundle 复制到本机后，先运行 `windows_build_testhost.ps1 -ManifestPath <build-manifest.json> -DryRun`，核对路径与 SHA；再无设备开关地运行同一脚本完成 Debug APK。只有用户明确选择时才附加 `-Install` 或 `-Run`。
|