99 lines
5.8 KiB
Markdown
99 lines
5.8 KiB
Markdown
# NESLite 构建与打包
|
||
|
||
项目的 APK 打包入口统一为根目录 `打包.cmd`,项目内的编译产物、缓存、日志和交付文件统一放入
|
||
`build/`。当前应用版本为 1.0.1,入口从 APK 构建元数据读取版本,不另写一套版本号。
|
||
|
||
## 一键打包
|
||
|
||
双击根目录的 **打包.cmd**。成功后窗口显示安装包完整路径,按回车关闭;失败时显示原因和日志位置。
|
||
默认生成可直接安装的 arm64 调试版,application ID 为 `org.neslite.app.debug`。
|
||
|
||
也可在 PowerShell 中执行:
|
||
|
||
```powershell
|
||
.\打包.cmd -NoPause
|
||
```
|
||
|
||
当前交付文件是 `build/releases/NESLite-1.0.1-debug-arm64-v8a.apk`,旁边的 `.sha256` 保存校验值。
|
||
入口检查工具链与固定依赖、编译选定 APK、检查原生库和 APK 的 16 KB 对齐,成功后复制产物。
|
||
它不会自动启动单元测试、ROM 遍历、设备测试或发布回归;失败会返回非零退出码,旧交付 APK 不冒充本次成功产物。
|
||
|
||
需要 Release 编译产物时使用同一个入口:
|
||
|
||
```powershell
|
||
.\打包.cmd release -NoPause
|
||
```
|
||
|
||
该模式使用项目外的正式密钥,生成 `build/releases/NESLite-1.0.1-arm64-v8a.apk`、原生符号、应用和依赖源码 ZIP、发布清单及校验值。
|
||
正式打包前必须提交源码并配置签名目录;入口读取 Windows 用户加密的密码,完成签名和签名验证。密钥位置与发布步骤见 [publishing.md](publishing.md)。
|
||
一键打包不会运行原 `package-rc.ps1` 的全量 Stage/lint/设备测试包构建,也不表示发布门槛通过。
|
||
|
||
## 工具链
|
||
|
||
需要 PowerShell 7、JDK 17、SDK Platform 36.1、Build Tools 36.1.0、NDK 28.2.13676358 与 CMake 3.22.1,
|
||
版本记录见 [toolchain.md](toolchain.md)。
|
||
|
||
- JDK 优先使用 `build/toolchains/jdk-17.0.17+10`,没有时使用 `JAVA_HOME`,启动前确认 Java 主版本为 17。
|
||
- SDK 依次读取 `local.properties` 的 `sdk.dir`、`ANDROID_HOME`、`ANDROID_SDK_ROOT`,最后尝试
|
||
`%LOCALAPPDATA%/Android/Sdk`。SDK 是本机外部依赖,不复制进项目。
|
||
- Gradle Wrapper 的 JAR、分发地址与校验值保留在 `gradle/wrapper/`,由新入口直接调用。
|
||
全局 Gradle 下载缓存仍使用用户原有配置,项目缓存放入 `build/cache/gradle`。
|
||
- `tools/fetch-third-party.ps1` 只负责检出固定依赖,由打包入口调用;已有依赖提交不匹配时停止,不覆盖源码。
|
||
首次缺少依赖时需要访问固定 Git 来源、Google Maven、Maven Central 和 Gradle 分发服务。
|
||
|
||
## 目录约定
|
||
|
||
| 路径 | 内容 |
|
||
| --- | --- |
|
||
| `build/app/` | Android 中间文件、原始 APK、测试结果和原生符号 |
|
||
| `build/native/app/` | Android CMake/Ninja 编译目录 |
|
||
| `build/root/` | 根 Gradle 项目生成文件 |
|
||
| `build/cache/` | 项目级 Gradle/Kotlin 缓存 |
|
||
| `build/tmp/` | 构建时的临时文件 |
|
||
| `build/releases/` | 版本化 APK、校验值、Release 符号和许可证材料 |
|
||
| `build/logs/` | 最近一次各模式的打包日志 |
|
||
| `build/reports/` | 原生审计与保留的历史诊断记录 |
|
||
| `build/toolchains/` | 项目本地 JDK;不是可随意删除的编译缓存 |
|
||
|
||
模块编译目录与 CMake 编译目录为并列目录,以符合
|
||
[AGP 对 CMake staging 目录的要求](https://developer.android.com/reference/tools/gradle-api/8.13/com/android/build/api/dsl/Cmake#buildStagingDirectory)。
|
||
Kotlin 的项目缓存通过其
|
||
[持久化目录配置](https://kotlinlang.org/docs/gradle-configure-project.html#kotlin-gradle-plugin-data-in-a-project)迁移。
|
||
|
||
## 按影响选择检查
|
||
|
||
打包和验收分开执行,按 `todo.md` 选择最小相关范围。需要 Kotlin 局部用例时,可直接调用保留的 Wrapper:
|
||
|
||
```powershell
|
||
$env:JAVA_HOME = (Resolve-Path build/toolchains/jdk-17.0.17+10).Path
|
||
$env:TEMP = (Resolve-Path build/tmp).Path
|
||
$env:TMP = $env:TEMP
|
||
$env:JAVA_TOOL_OPTIONS = "-Djava.io.tmpdir=`"$env:TEMP`" -Djdk.net.unixdomain.tmpdir=`"$env:TEMP`""
|
||
& "$env:JAVA_HOME/bin/java.exe" -classpath gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain --project-cache-dir build/cache/gradle :app:testDebugUnitTest --tests org.neslite.app.BuildIdentityTest
|
||
```
|
||
|
||
原生测试在 `build/native-tests` 配置后,只构建和运行相关目标,例如显示修复:
|
||
|
||
```powershell
|
||
$taskCmake = "$env:LOCALAPPDATA/Android/Sdk/cmake/3.22.1/bin"
|
||
& "$taskCmake/cmake.exe" -S app/src/main/cpp -B build/native-tests
|
||
& "$taskCmake/cmake.exe" --build build/native-tests --config Debug --target neslite_video_viewport_test
|
||
& "$taskCmake/ctest.exe" --test-dir build/native-tests -C Debug --output-on-failure -R '^neslite_video_viewport_test$'
|
||
```
|
||
|
||
单 ROM 桌面诊断见 [探针说明](../tools/rom-probe/README.md)。`tools/check-m1-device.ps1` 只安装和启动已构建
|
||
的调试 APK,`tools/check-rc-native.ps1` 只审计现有 APK;它们不是另一个编译入口。ROM 样本生成与长稳采集
|
||
脚本的默认输出也已改到 `build/`,专项按 [acceptance.md](acceptance.md) 执行。
|
||
|
||
## 清理与历史记录
|
||
|
||
旧的 `tools/check.ps1`、`tools/package-rc.ps1`、`gradlew`、`gradlew.bat` 已由 `打包.cmd` 替代。
|
||
旧 `.build/`、`app/build/`、`app/.cxx/`、项目根 `.gradle/`、`.kotlin/` 及重复工具链目录已清理;
|
||
保留的本地 JDK 已迁入 `build/toolchains/`。Gradle/CMake 配置、Wrapper JAR 和锁定信息是编译依赖,继续保留。
|
||
|
||
历史报告中的命令和产物路径记录当时状态,不再作为现行入口。保留的旧日志、审计 JSON 与 ROM 诊断画面
|
||
归档在 `build/reports/history/`;历史 APK 和候选发布材料迁入 `build/releases/history/`,可重新生成的旧编译目录已删除。
|
||
|
||
日常清理可删除 `build/app`、`build/native`、`build/root`、`build/cache`、`build/tmp` 等生成目录;
|
||
保留 `build/toolchains` 和需要留存的交付/验收记录。整个 `build/` 不进入 Git;不要删除外部 SDK、签名密钥或 ROM。
|