拆解artcraft-android构建流水线:8个阶段与build-common.sh主编排器深度解析
拆解artcraft-android构建流水线:8个阶段与build-common.sh主编排器深度解析
artcraft-android 是一个开源的 Android 移植构建器,它把 14 款 ArtCraft 桌面创作应用(PhotoCraft、VectorCraft、SubCraft 等)编译成本地签名的 64 位 ARM APK。整条构建流水线由 build-common.sh 这一主编排器驱动,从工具链自检、SDK 自动引导,到源码校验、启动器生成、签名打包,共划分为 8 个可观察阶段。本文用通俗的方式带你完整走完这条流水线。
一个大脑,两个入口:build.sh 与 build-debug.sh
流水线有两个极简入口脚本,它们只负责一件事——定位自身并把控制权交给主编排器:
| 入口脚本 | 作用 |
|---|---|
| build.sh | 构建优化后的 release APK |
| build-debug.sh | 构建体积更大、便于排查问题的 debug APK |
两个脚本的核心逻辑完全一致(见 build.sh#L3-L4):解析自身所在目录,然后 exec bash lib/build-common.sh release/debug "$@"。真正的"大脑"是长达 4150 行的 lib/build-common.sh,它按 say 1 到 say 8 打印 8 个阶段进度,每一步都可独立定位排查。
8 个阶段速览
| 阶段 | 提示语 | 做什么 | 源码位置 |
|---|---|---|---|
| 1 | Checking build tools... | 检查 git / Cargo / Python 3.11+ / cargo-ndk | L197-L227 |
| 2 | Finding Android SDK and NDK... | 发现或自动下载 SDK、NDK、Gradle JDK | L426-L457 |
| 3 | Fetching official source... | 克隆/复用上游客源并做完整性校验 | L459-L591 |
| 4 | Preparing the GameActivity launcher... | 准备 Android 启动器(适配器或自动生成) | L593-L829 |
| 5 | Preparing a builder-owned signing key... | 生成或复用本地 JKS 签名密钥 | L3973-L4000 |
| 6 | Building $TITLE... | cargo-ndk 编译 + Gradle 打包签名 | L4002-L4136 |
| 7 | Verifying the Android file bridge... | 验证 APK 里的启动 Activity 与原生库 | L4138-L4139 |
| 8 | Build succeeded. | 输出 APK、体积、SHA-256 与日志 | L4141-L4149 |
阶段 1-2:零配置引导工具链
阶段 1 会依次验证 git、Cargo、Python 3.11+(需要 tomllib 解析清单文件),并在缺少 cargo-ndk 时自动执行 cargo install cargo-ndk --locked 安装。
阶段 2 是"零配置"体验的关键:编排器会按环境变量 → 项目内 android-sdk/ → 常见系统路径的顺序寻找 Android SDK;缺失时自动从 Google 官方仓库索引解析最新版 command-line tools 下载地址并安装 platform、build-tools 与 NDK。Gradle 需要的 JDK 也走同样的策略——优先用本机 JDK 17-23,找不到就自动下载 Temurin 21 到 .cache/jdk(见 bootstrap_gradle_jdk)。这意味着一台几乎"裸机"的开发机也能直接跑通流水线。
阶段 3:源码获取与完整性校验 🛡️
这一阶段体现了流水线对"翻车场景"的深度思考:
- 复用优先:若
source/<app>/已存在,则校验其 Git origin 是否匹配、工作树是否完整(source_tree_is_complete),避免覆盖你在本地做的移植修改; - 防断克隆:新克隆先落到临时目录
source/.clone-$APP.$$,验证crates/与apps/下所有被跟踪文件都在磁盘上,才允许正式落位,防止"被杀进程/磁盘写满"造成的半截克隆被后续构建误用; - 版本策略:默认
-stable通过git ls-remote解析最新的v*发布 tag,也可用-main、-tag=<tag>、-branch=<branch>切换; - 上游热修复:对上游
main上已知的编译回归,内嵌的 Python 补丁会"条件修复"——只有坏代码仍在时才动手(L545-L580)。随后由 lib/scrolling.sh(双指滚动)和 lib/subcraft.sh(SubCraft 文件投递)分别打上应用层补丁。
阶段 4:启动器准备——两种移植模型
阶段 4 决定"谁来启动这个 App",支持两种模型(详见 adapters/README.md):
- 定制适配器:若
adapters/<app>/prepare.sh存在(如 adapters/photocraft/prepare.sh),直接运行它。适配器自带 Java Activity(如 PhotoCraftActivity.java)实现 SAF 文件选择等深度集成; - 自动生成器:否则由 build-common.sh 内嵌的 Python 生成器扫描上游 workspace,合成
apps/<app>-android/启动器,并从 templates/android/ 拷入共享运行时模块(system_fonts.rs、ime_bridge.rs、saf_bridge.rs、UpdateCheck.java),再借助 lib/app_icons.py 生成分辨率分级的启动图标、用 lib/file_associations.py 写入文件关联的 intent filter。生成器带版本号标记(当前为GENERATOR_VERSION="61"),模板升级后可自动重建旧启动器。
阶段 5-6:签名密钥与编译打包
阶段 5 在 keys/ 下用 keytool 生成 RSA-2048 JKS 密钥对(密码用 secrets 随机生成),目录权限收紧到 700/600,保证同一构建者后续版本可"覆盖安装"。
阶段 6 是火力全开的部分:
- 先读取 workspace 的
version作为 APK 版本号,让产物落地为output/<app>-<version>.apk; - 用
cargo ndk -t arm64-v8a把原生库编译进jniLibs; - 由 lib/android_project.py 每次重新生成
AndroidManifest.xml、主题资源与 Gradle 工程(AGP 8.7.3,Gradle wrapper 来自 templates/gradle/); - 最后执行
./gradlew assembleRelease(或assembleDebug),通过ARTCRAFT_KEYSTORE*环境变量注入签名,并原子化地把 APK 拷贝到output/。
阶段 7-8:产物验证与交付
"构建成功"不等于"能装能跑"。阶段 7 的 verify_android_bridge 会用 aapt2 dump badging 确认 APK 里真的存在可启动的 launcher activity,并用 Python 扫描 dex 与 .so,确保 Java SAF 桥和原生库都被打进包里——否则宁可报错也不放行。阶段 8 输出应用名、模式、APK 路径、体积、SHA-256 与日志文件位置,收尾干净利落。
让流水线更可靠的工程细节 🔧
- 全局锁:
flock保证同一时间只有一个构建在跑,避免两个构建互相替换启动器 crate 导致"Could not determine current working directory"的诡异错误(L179-L195); - 失败必留名:
trap ERR会打印出错的具体行号和命令,日志永远说得清"死在哪"; - 只加不删:所有失败路径都会明确提示"未删除任何源码与项目文件",本地移植成果受保护;
- CI 协同:GitHub Actions 用 14 个 App 的并行矩阵 + sccache/Cargo/Gradle 三层缓存调用同一条流水线,设计细节见 docs/ci-workflow.md。
相关文件清单
| 文件 | 角色 |
|---|---|
| lib/build-common.sh | 主编排器(8 阶段全在此) |
| lib/android_project.py | 生成 Manifest 与 Gradle 工程 |
| lib/app_icons.py / lib/file_associations.py | 图标与文件关联生成 |
| lib/scrolling.sh / lib/ime.sh / lib/subcraft.sh | 应用层运行时补丁 |
| adapters/ | PhotoCraft / VectorCraft / SubCraft 定制适配器 |
| clean.sh | 一键清理 source/、build/、output/、keys/ 等构建状态 |
| architecture.md | 完整架构技术参考 |
一句话总结:artcraft-android 的构建流水线把"装环境、拉源码、做移植、编产物、验产物"全部收敛进一个带 8 个进度阶段的主编排器,配合锁、trap 和完整性校验,让"一行 bash build.sh -photocraft"就能在裸机上得到一个可安装的 APK——这正是它最值得拆解和借鉴的地方。
