Build from Source

从源码构建

🛠️ 工程化 · 🏠 首页 › Build-from-Source

---

📑 本页目录

• 1. 前置条件
• 2. 第一次构建
• 3. 常用构建命令
• 4. 内置 Ubuntu rootfs 的两种来源
• 5. 构建配置里的"为什么"
• 6. 常见构建失败
• 7. 相关页面

主线 Gradle 8.10 + JDK 17 + Android SDK 35 + NDK 27（terminal 原生层需要）。 仓库未锁定 wrapper，这是刻意的（避免 wrapper jar 进 git），但第一次要现场生成。

1. 前置条件

依赖	版本	校验命令
JDK	17（Temurin 推荐）	java -version
Android SDK	compileSdk 35、build-tools、platform-tools	sdkmanager --list_installed
NDK	27.0.12077973	AGP 会自动提示安装
Gradle	8.10	gradle --version（或用 Android Studio 自带）
（可选）cmake/ninja	CMake 3.22.1	通常由 SDK Manager 提供

Warning

Windows / macOS / Linux 均可构建；Windows 下请确保 Git 未把 .sh 转成 CRLF （scripts/*.sh 需要 LF + 可执行权限，否则 CI/本地跑会失败）。

2. 第一次构建

git clone https://github.com/AceGuru-mjh/Android-Guru-Agent.git
cd Android-Guru-Agent

# 1) 现场生成 wrapper（仅首次）
gradle wrapper --gradle-version 8.10
chmod +x gradlew

# 2) 编译 / 打 debug 包
./gradlew :app:assembleDebug --stacktrace

产物：app/build/outputs/apk/debug/app-debug.apk

参考 CI 的等价做法：.github/workflows/ci.yml 的 Configure pre-installed Android SDK 步骤 + Generate Gradle wrapper 步骤 + 依赖预热（JitPack 需要重试）。

3. 常用构建命令

目的	命令
Debug APK	./gradlew :app:assembleDebug
Release APK	./gradlew :app:assembleRelease
单 ABI 瘦身包	./gradlew :app:assembleRelease -PapexAbi=arm64-v8a
只编译 Kotlin	./gradlew :app:compileDebugKotlin
编译仪器测试	./gradlew :platform:terminal:assembleDebugAndroidTest
内置 Ubuntu rootfs 暂存	scripts/fetch_rootfs.sh（或 --check 快速校验）
全量测试	见 测试体系

4. 内置 Ubuntu rootfs 的两种来源

方式	说明
内置（默认，v1.2.0 起）	由 scripts/fetch_rootfs.sh 在构建期把官方归档暂存为 libubuntu-rootfs.so，随 APK 分发，用户无需下载
--check 快速路径	只校验已暂存档案指纹，不下载（CI 用）

说明：

• 若 jniLibs 目录里已有符合指纹的存档，脚本走幂等路径（跳过下载、只校验）；
• 若想彻底不带内置 rootfs（体积更小、迭代更快），先 --clean 再跳过该步骤， 终端屏会回退到"按需下载"路径。 详见 Ubuntu rootfs 供给。

5. 构建配置里的"为什么"

配置	位置	原因
targetSdk = 28	app/build.gradle.kts	见 终端运行时
ExpiredTargetSdkVersion lint 关闭	同上	我们知道它过期，注释里写明了理由
useLegacyPackaging = true	terminal + app	.so（含 rootfs 归档）必须解压才能 exec/读取
keepDebugSymbols += "**/libubuntu-rootfs.so"	同上	防止 llvm-strip 损坏归档
dependencyLocking	:app	锁定解析结果，避免依赖漂移导致 CI 与本地不一致
RepositoriesMode.FAIL_ON_PROJECT_REPOS	settings.gradle.kts	禁止模块私开仓库，仅 JitPack（EasyFloat）例外
ABI filters	terminal 模块	arm64-v8a / armeabi-v7a / x86_64

6. 常见构建失败

报错	处理
gradlew: command not found	仓库没锁 wrapper，先跑 gradle wrapper --gradle-version 8.10
NDK missing / CMake missing	让 AGP 自动安装或 sdkmanager "ndk;27.0.12077973" "cmake;3.22.1"
JitPack 下载超时	依赖有重试策略；多试几次或换网络（CI 里也是重试的）
scripts/fetch_rootfs.sh 报 digest mismatch	暂存档案损坏 → --clean 后重新拉取
Kotlin 编译内存溢出	提高 gradle.properties 的 org.gradle.jvmargs（如 -Xmx4g）
strip 报 rootfs 归档失败	keepDebugSymbols 未生效，检查两处配置是否都在
Windows 上 bash 脚本 "\r": command not found	用 LF 换行并在 PowerShell 里确保执行策略允许

7. 相关页面

• CI 流水线 · 质量门禁 · 仓库脚本
• Ubuntu rootfs 供给 · 测试体系

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}