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