release: prepare NESLite 1.0.0 with dual cores and signed packaging

This commit is contained in:
2026-09-14 17:30:37 +08:00
parent e3842c21dc
commit fefca3ca68
68 changed files with 1819 additions and 592 deletions
+73 -57
View File
@@ -1,82 +1,98 @@
# NESLite 可复现构建说明
# NESLite 构建与打包
本说明对应 0.9.15 候选基线。命令使用系统默认 PowerShell 7.6.6(`pwsh`)从仓库根目录执行;不需要手工复制 `.so`、
FCEUmm 或 Oboe 文件。
项目的 APK 打包入口统一为根目录 `打包.cmd`,项目内的编译产物、缓存、日志和交付文件统一放入
`build/`。当前应用版本为 1.0.0,入口从 APK 构建元数据读取版本,不另写一套版本号。
## 前置条件
## 一键打包
1. 安装或使用 [toolchain.md](toolchain.md) 中的 JDK 17.0.17+10、SDK Platform 36.1、
NDK 28.2.13676358 与 Android CMake 3.22.1。
2. 设置 `JAVA_HOME` 指向 JDK 17;不能用系统默认的 JDK 21。
3. 设置 `ANDROID_HOME`(或在未设置时使用本机记录的 SDK 根目录)。`local.properties` 仅保存
本机 `sdk.dir`,不提交。
4. 首次构建需要访问 Google Maven、Maven Central 与 Gradle 分发服务,以取得已锁定版本。
5. M2~M4 构建原生内核、音频和输入层前,运行:
双击根目录的 **打包.cmd**。成功后窗口显示安装包完整路径,按回车关闭;失败时显示原因和日志位置。
默认生成可直接安装的 arm64 调试版,application ID 为 `org.neslite.app.debug`。
```powershell
.\tools\fetch-third-party.ps1
```
该脚本根据 `third_party/manifest.json` 检出固定提交;M4 构建需要 FCEUmm、libretro headers 与 Oboe。
## 构建调试 APK
也可在 PowerShell 中执行:
```powershell
pwsh -NoProfile -File .\tools\check.ps1 -Scope Build
.\打包.cmd -NoPause
```
产物为 `app/build/outputs/apk/debug/app-debug.apk`,其中只包含 `arm64-v8a` 的
`libneslite_jni.so`。调试包的 application ID 是 `org.neslite.app.debug`。
当前交付文件是 `build/releases/NESLite-1.0.0-debug-arm64-v8a.apk`,旁边的 `.sha256` 保存校验值。
入口检查工具链与固定依赖、编译选定 APK、检查原生库和 APK 的 16 KB 对齐,成功后复制产物。
它不会自动启动单元测试、ROM 遍历、设备测试或发布回归;失败会返回非零退出码,旧交付 APK 不冒充本次成功产物。
## 有界检查入口
| 命令 | 范围 | 不会执行 |
| --- | --- | --- |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Build` | 生成调试 APK | 单元、原生、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Local` | Kotlin 本地单元测试 | APK、原生、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Module` | 原生 smoke test 与 Kotlin 本地单测 | APK、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Stage` | 当前 APK、原生 smoke test 与 Kotlin 本地单测 | 设备、ROM 兼容、耐久、H 专项 |
`Stage` 是本地阶段入口,不是 G1~G9 的替代。实机、ROM、存档、插拔和耐久验收必须在
相应里程碑按 [acceptance.md](acceptance.md) 执行和记录。
## 构建候选交付材料
先提交所有候选源码并保持工作区干净,然后执行:
需要 Release 编译产物时使用同一个入口:
```powershell
pwsh -NoProfile -ExecutionPolicy Bypass -File .\tools\package-rc.ps1
.\打包.cmd release -NoPause
```
脚本重跑 Stage 和 release lint,生成 `org.neslite.app` 的未签名 release APK、完整原生符号、应用及
三个固定第三方依赖的源码包、许可证/说明、静态原生审计、候选清单和 SHA-256。输出位于
`.build/rc-0.9.15/`。静态审计逐个检查 APK 内 `.so` 的 ELF LOAD 段和 APK 16 KB 对齐,并拒绝非
arm64-v8a 库。
该模式使用项目外的正式密钥,生成 `build/releases/NESLite-1.0.0-arm64-v8a.apk`、原生符号、应用和依赖源码 ZIP、发布清单及校验值。
正式打包前必须提交源码并配置签名目录;入口读取 Windows 用户加密的密码,完成签名和签名验证。密钥位置与发布步骤见 [publishing.md](publishing.md)。
一键打包不会运行原 `package-rc.ps1` 的全量 Stage/lint/设备测试包构建,也不表示发布门槛通过。
默认 APK 刻意保持未签名;发布私钥和口令不得传入仓库或写入脚本。获得受保护的发布密钥后,在隔离
环境签名并重新执行对齐/签名/设备检查。未签名包不能用于安装、覆盖升级或 G8 运行验收。
## 工具链
冻结的 12 个 CC0 最小 ROM 冒烟样本可用下列命令在忽略目录重建:
需要 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
pwsh -NoProfile -ExecutionPolicy Bypass -File .\tools\generate-rc-roms.ps1
$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
```
它们不包含游戏素材,也不能替代音画、滚屏、电池进度和长稳所需的合法代表游戏样本。设备长稳采集
入口为 `tools/collect-h-long.ps1`;默认 120 分钟、60 秒一次,只负责采集,不自动批准内存趋势。
## M1 诊断版安装
连接并授权一台目标手机后执行:
原生测试在 `build/native-tests` 配置后,只构建和运行相关目标,例如显示修复:
```powershell
pwsh -NoProfile -File .\tools\check-m1-device.ps1
$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$'
```
脚本安装并启动 `0.1.3-debug` 诊断版;手柄操作和导出步骤见
[controller-x5lite.md](controller-x5lite.md)。连接多台设备时传入 `-Serial <adb序列号>`。
单 ROM 桌面诊断见 [探针说明](../tools/rom-probe/README.md)。`tools/check-m1-device.ps1` 只安装和启动已构建
的调试 APK,`tools/check-rc-native.ps1` 只审计现有 APK;它们不是另一个编译入口。ROM 样本生成与长稳采集
脚本的默认输出也已改到 `build/`,专项按 [acceptance.md](acceptance.md) 执行。
## 清理
## 清理与历史记录
只清理本工程生成物时删除 `build/`、`app/build/` 和 `.build/`;不要删除 SDK、NDK、
`.toolchains/` 或用户的签名密钥。上述输出均已被 Git 忽略。
旧的 `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。