Files
NESLite/docs/build.md
T

99 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# NESLite 构建与打包
项目的 APK 打包入口统一为根目录 `打包.cmd`,项目内的编译产物、缓存、日志和交付文件统一放入
`build/`。当前应用版本为 1.0.4,入口从 APK 构建元数据读取版本,不另写一套版本号。
## 一键打包
双击根目录的 **打包.cmd**。成功后窗口显示安装包完整路径,按回车关闭;失败时显示原因和日志位置。
默认生成可直接安装的 arm64 调试版,application ID 为 `org.neslite.app.debug`。
也可在 PowerShell 中执行:
```powershell
.\打包.cmd -NoPause
```
当前交付文件是 `build/releases/NESLite-1.0.4-debug-arm64-v8a.apk`,旁边的 `.sha256` 保存校验值。
入口检查工具链与固定依赖、编译选定 APK、检查原生库和 APK 的 16 KB 对齐,成功后复制产物。
它不会自动启动单元测试、ROM 遍历、设备测试或发布回归;失败会返回非零退出码,旧交付 APK 不冒充本次成功产物。
需要 Release 编译产物时使用同一个入口:
```powershell
.\打包.cmd release -NoPause
```
该模式使用项目外的正式密钥,生成 `build/releases/NESLite-1.0.4-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。