Files
NESLite/docs/build.md
T

5.8 KiB
Raw Blame History

NESLite 构建与打包

项目的 APK 打包入口统一为根目录 打包.cmd,项目内的编译产物、缓存、日志和交付文件统一放入 build/。当前应用版本为 1.0.1,入口从 APK 构建元数据读取版本,不另写一套版本号。

一键打包

双击根目录的 打包.cmd。成功后窗口显示安装包完整路径,按回车关闭;失败时显示原因和日志位置。 默认生成可直接安装的 arm64 调试版,application ID 为 org.neslite.app.debug。

也可在 PowerShell 中执行:

.\打包.cmd -NoPause

当前交付文件是 build/releases/NESLite-1.0.1-debug-arm64-v8a.apk,旁边的 .sha256 保存校验值。 入口检查工具链与固定依赖、编译选定 APK、检查原生库和 APK 的 16 KB 对齐,成功后复制产物。 它不会自动启动单元测试、ROM 遍历、设备测试或发布回归;失败会返回非零退出码,旧交付 APK 不冒充本次成功产物。

需要 Release 编译产物时使用同一个入口:

.\打包.cmd release -NoPause

该模式使用项目外的正式密钥,生成 build/releases/NESLite-1.0.1-arm64-v8a.apk、原生符号、应用和依赖源码 ZIP、发布清单及校验值。 正式打包前必须提交源码并配置签名目录;入口读取 Windows 用户加密的密码,完成签名和签名验证。密钥位置与发布步骤见 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。

  • 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 目录的要求。 Kotlin 的项目缓存通过其 持久化目录配置迁移。

按影响选择检查

打包和验收分开执行,按 todo.md 选择最小相关范围。需要 Kotlin 局部用例时,可直接调用保留的 Wrapper:

$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 配置后,只构建和运行相关目标,例如显示修复:

$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/check-m1-device.ps1 只安装和启动已构建 的调试 APK,tools/check-rc-native.ps1 只审计现有 APK;它们不是另一个编译入口。ROM 样本生成与长稳采集 脚本的默认输出也已改到 build/,专项按 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。