37 lines
3.5 KiB
Markdown
37 lines
3.5 KiB
Markdown
# Windows 与 Linux 功能交付约定
|
||
|
||
文档版本：1.1.1
|
||
修订日期：2026-09-12
|
||
核对代码基线：`22579e5`；本次版本号仅标注文档，不改变模型版本或协议版本。
|
||
|
||
2026-09-12 用户明确要求：后续功能补全同时注意 Windows 平台适配。
|
||
|
||
Windows x64 与 Linux x86_64 都是当前应用的使用平台。涉及文件系统、缓存、编译器、进程、动态库、环境安装或启动脚本的功能修改，应同时检查两侧的实现和测试入口。
|
||
|
||
- 文件系统可选能力应按运行环境检测，例如 `os.supports_follow_symlinks`，不能因为 Linux 接受某个参数就假设 Windows 也接受。缓存目录仍需验证普通目录、符号链接与 Windows reparse point；权限和真实 I/O 错误不能当成兼容问题随意吞掉。
|
||
- 编译与运行应覆盖 Windows 的 `.exe`、导入库/DLL、工具链路径、带空格路径和换行行为。进程锁、并发清理、异常退出应有可在 Windows 执行的测试。
|
||
- 平台专用的小型测试夹具可以明确限定平台，但不能代替跨平台集成测试。Windows CI 中必需的工具链缺失应失败，不能以整组跳过得到成功结论。
|
||
- 交付记录分别列出兼容代码、模拟测试、实际 Windows 测试的状态。只有实际 Windows 运行通过，才能声称 Windows 验收通过。缺少 Windows 环境时继续完成可做的修复和测试准备，并明确实机验证仍待完成。
|
||
- 本地虚拟环境、编译器、便携运行时和构建缓存保留在 Git 忽略目录，不随源码提交。
|
||
|
||
当前缓存检查入口：
|
||
|
||
```powershell
|
||
$env:SIMULATION_NATIVE_REQUIRE_TOOLCHAIN = '1'
|
||
.\.venv-win\Scripts\python.exe -m unittest tests.test_native_cache_storage tests.test_native_cache_platform -v
|
||
```
|
||
|
||
该入口使用现有 `SIMULATION_NATIVE_CC` / `SUNDIALS_ROOT` 或构建器的默认探测；CI 配置在 `.github/workflows/solver-regression.yml` 的 `native-windows` 作业。
|
||
|
||
新增组件同样适用本约定：新增 C 模块应使用现有构建抽象和严格浮点设置，检查模块导出、传递依赖、对象复用、完整模型缓存、Windows 可执行文件与 DLL 发现；不要在组件脚本中写死 Linux 编译器、路径分隔或符号链接能力。
|
||
|
||
[注册演练](component-registration-example-v1.md)在 Linux 使用真实浏览器和 C 工具链执行；本次没有 Windows 实机环境，未宣称演练已通过 Windows 验收。复现工具使用 `sys.executable`、`pathlib`、无 shell 的编译调用；Windows 验收仍需实际执行。
|
||
|
||
## 当前工具链边界（2026-09-12 核对）
|
||
|
||
构建器只接受 Windows/Linux，默认寻找 `gcc`，或读取 `SIMULATION_NATIVE_CC`；使用 GCC 风格的预处理、目标查询和编译参数，不承诺 MSVC/macOS 支持。公共参数包括 C11、`-O3 -Wall -Wextra -Werror -ffp-contract=off -fno-fast-math`。Windows 另加 MinGW printf 与静态 libgcc 选项，Linux 添加 POSIX 宏。
|
||
|
||
`SUNDIALS_ROOT` 指向开发文件根目录：Windows 使用 `lib/sundials_*.lib` 和 `bin/sundials_*.dll`，将依赖 DLL 随模型复制；Linux 使用探测目录中的 `libsundials_*.a` 静态链接。当前五个链接库为 cvode、core、nvecserial、sunmatrixdense、sunlinsoldense，RK45 构建也使用这套共用程序。
|
||
|
||
CI 的 `native-windows` 配置了 MinGW、SUNDIALS、缓存回归、后端完整回归和原生 RK45 夹具；其存在不证明任意一次修改已经在 Windows 运行通过。本次仅核对配置并运行本机可执行检查，未取得新的 Windows 实机结果。
|