构建 Java 8 / Java 21 双目标

当前源码位于 src/main/java/polaris/sdk/ui/。JNI 导出已同步新包名，修改包名后不能继续使用旧的 native 二进制。

编译 Java 与资源

根目录 build.cmd all / sh build.sh all 使用本机 JDK 21+ 一次构建两种目标。build.cmd 8 只构建 Java 8，可由本机 JDK 8 或更新版本完成；build.cmd 21 需要 JDK 21+。

使用现代编译器时分别指定 --release 8、--release 21。真正 JDK 8 的路径使用其自身平台类与 -source 1.8 -target 1.8。脚本不会声称在 JDK 8 上能编译 Java 21 目标。

Java 8 构建中间产物位于 build/classes，Java 21 位于 build/classes21；公开发行物在各自 jdk8/ / jdk21/ 目录。两者使用同一份源代码、GLSL 和 native，不增加虚拟线程来运行 OpenGL，也不编造不存在的 JDK 21 专用优化。

代码构建不要求联网、Maven、Gradle、Python 或 C 编译器。修改 Java 或 GLSL 后重新运行即可。不要将旧 2.3 native 与新 Java 单独混装；2.4 指令步长已更新，启动时会检查 native protocol 版本。

API 文档

build-docs.cmd / sh build-docs.sh 用 JDK 自带 Javadoc 从实际源码生成 docs/javadoc/，并生成两个目标的 Javadoc JAR。API 相同，因此文档内容共用，目标字节码差异不会改变公开签名。

同一脚本把中文 Markdown 文档生成离线 HTML，刷新 docs/、examples/ 和 README 页面。字体文件会被过滤掉，不把 JDK Javadoc 可能附带的 web 字体分发出去。

编译运行示例

compile-examples.cmd 8 和 compile-examples.cmd 21 分别直接引用开发包内的对应 library JAR 编译，而不是偷偷依赖源码树。输出位于 build/examples-jdk8 / build/examples-jdk21。

run-example.cmd 8 Main 或 sh run-example.sh 21 RenderingQuality 会编译并启动选定 main。HostIntegration 没有 main，需要由已有渲染器调用。

native

修改 C 后才需要以下命令。Linux 本机构建：

sh native/build-linux.sh

Windows x64 DLL 也可通过 clang / lld-link 交叉构建：

sh native/build-windows-cross.sh

也保留 native/build-windows.cmd 的 MSVC 源码构建入口。本次包名迁移在 Windows 使用 clang / LLD 重建 DLL、Zig 交叉重建 Linux SO。Windows 已执行本包 JNI 的真实 OpenGL 绘制检查；Linux SO 只验证了编译与导出，未做 Linux 运行测试。

两个 Java 目标共用相同 JNI/native ABI。平台层的固定 HDC、context 验证后切换、legacy 回退和 WGL 错误记录保留，没有因这次文本/曲线更新重写。

测试

包名迁移检查使用 PowerShell 7、完整 JDK 和 LLVM 的 llvm-readobj：pwsh -File tests/verify-namespace.ps1 -ReadObject llvm-readobj。检查两个目标的逻辑测试、99 个公开类的签名、JAR 包路径和两平台 15 个 JNI 导出。-BaselineSdk 可指定改名前的完整 SDK ZIP，核对除包名以外的公开 API 没有变化。结果写入 tests/results/package-migration/；tests/verify-release.py 及旧版结果保留为迁移前的历史审计。

添加 -NativeSmoke 会使用屏幕外 AWT 窗口验证本机 JNI 加载、真实 OpenGL 绘制与 framebuffer 读取，需要桌面环境及 OpenGL 3.3+；不会注入鼠标或键盘操作。

构建 SDK ZIP 后执行 pwsh -File tests/verify-license.ps1，核对 8 个 JAR 和完整包携带的许可、历史 MIT 记录及第三方声明。Java 构建与 Javadoc 构建会自动把这些文件放入 META-INF/；直接分发单个 JAR 时也保留声明。

原有 tests/run-logic.sh、run-motion.sh、run-neutral.sh、run-stepper.sh、run-gpu.sh、run-window.sh 等仍使用 Java 8 构建目录。

新增：

sh tests/run-quality.sh
sh tests/run-quality-window.sh

运行 GPU 测试需要 Linux Mesa/EGL 或相应图形驱动；窗口测试需要 X11/Xvfb。只有截图和像素测试读回 framebuffer，正常 UI 渲染没有逐帧 glReadPixels。

可选 Maven 入口

保留的 pom.xml 默认构建 Java 8 目标，mvn -Pjdk21 package 可选择 Java 21 目标。Maven 产物在 target/，不是离线脚本的双目标目录。Maven 插件首次可能需要联网下载；当前验证使用的是 JDK 离线构建路径，没有把 Maven 命令记为已执行通过。

2.4.4 场景检查

新增 sh tests/run-scenes.sh（模型与多尺寸布局）和 sh tests/run-scenes-window.sh（真正窗口、鼠标与键盘操作）。先执行 sh build.sh all。窗口测试需要 Linux Xvfb / Mesa，测试不是 Windows 实机结果。

七个新示例入口随全部20个示例一起构建，compile-examples.sh 8 与 compile-examples.sh 21 直接引用最终 library JAR 再次编译。展示源码的 --scene 跳转不影响已有 --page 索引。