znlgis 博客

GIS开发与技术分享

第14章：构建、测试、调试与贡献流程

1. 构建前准备

OpenSCAD 官方 README 明确列出构建依赖：C++17 编译器、CMake、Qt、QScintilla、CGAL、GMP、MPFR、Boost、OpenCSG、GLEW、Eigen、glib2、fontconfig、freetype、harfbuzz、libzip、Bison、Flex、pkg-config、double-conversion 等。测试还需要 Python3、Ghostscript、Catch2。

这些依赖说明 OpenSCAD 是一个复杂桌面应用和几何软件，不是单个小型库。源码开发前应准备稳定环境。

2. Linux/BSD 构建

官方提供依赖脚本：

git submodule update --init --recursive
sudo ./scripts/uni-get-dependencies.sh qt6
./scripts/check-dependencies.sh
cmake -B build -DEXPERIMENTAL=1
cmake --build build
cd build && ctest

不同发行版包名和版本差异很大。如果依赖过旧，可使用官方脚本构建部分依赖到用户目录。

3. macOS 构建

macOS 需要 Xcode、Homebrew 和一系列构建工具。官方 README 提到可使用：

source scripts/setenv-macos.sh
./scripts/macosx-build-dependencies.sh

或 Homebrew 路径：

./scripts/macosx-build-homebrew.sh

macOS 调试 GUI 时要关注应用包、签名、Qt 插件路径和系统权限。

4. Windows 构建

Windows 通常从 Linux 交叉编译，也有 MSVC 构建说明。交叉编译依赖 MXE，过程耗时并占用大量磁盘。普通贡献者如果只改语言、测试或文档，不必一开始完成完整 Windows 打包；但涉及平台路径、GUI、OpenGL、字体或安装器时必须验证 Windows 行为。

5. WebAssembly 构建

官方 README 提到使用 Emscripten 和 Docker 镜像构建 headless WebAssembly：

./scripts/wasm-base-docker-run.sh emcmake cmake -B build-web -DCMAKE_BUILD_TYPE=Debug -DEXPERIMENTAL=1
./scripts/wasm-base-docker-run.sh cmake --build build-web -j2

WASM 适合浏览器演示、在线编辑器和服务端无 GUI 集成，但功能和性能边界需要单独评估。

6. 测试体系

官方仓库 tests 目录包含 CMake 测试配置、Python 测试、命令行工具测试、STL 验证、PNG 导出/比较、回归数据等。几何软件测试难点在于结果既有数值性质，又有视觉性质。

测试类型可分为：

  • 语法和语言行为测试。
  • 命令行参数测试。
  • 导入导出格式测试。
  • 渲染回归图片测试。
  • STL 合法性测试。
  • GUI 行为测试。
  • WebAssembly 检查。

7. 调试策略

语言问题

准备最小 .scad：

x = 10;
echo(x);
cube(x);

跟踪解析、AST、上下文和表达式求值。

几何问题

准备最小布尔模型，降低 $fn，用 F5/F6 对比，观察是否自交、共面、非流形。

导出问题

使用命令行固定输入输出，检查文件大小、日志、错误码和导出格式推断。

GUI 问题

确认是否能在命令行复现。如果不能，问题可能在 Qt 信号槽、视图状态、设置、线程或平台特定行为。

8. 贡献流程

官方 README 建议通过 GitHub issue 讨论变更。想处理现有 issue 时，可按项目规则在 issue 评论中使用 /assign-me。通用贡献步骤：

  1. 搜索现有 issue 和 PR，避免重复。
  2. 用最小示例说明问题或需求。
  3. 建立本地构建和测试环境。
  4. 小步提交，保持变更范围明确。
  5. 增加或更新测试。
  6. 更新用户可见文档或帮助信息。
  7. 在 PR 中说明平台、测试命令和兼容性影响。

9. 代码修改建议

  • 修改语言语义前先写测试。
  • 修改几何算法前准备多个退化案例。
  • 修改 GUI 前检查无 GUI 命令行是否受影响。
  • 修改导出格式前准备导入其他软件验证。
  • 不要在修复小 bug 时顺手重构大范围代码。
  • 跨平台路径必须使用已有平台抽象。
  • 错误消息应面向用户，而不是只给核心开发者看。

10. 本地验证清单

  • cmake -B build -DEXPERIMENTAL=1 成功。
  • cmake --build build 成功。
  • ctest 或相关子集通过。
  • 新增 .scad 回归样例能复现问题。
  • 命令行导出返回正确错误码。
  • GUI 路径无明显回归。
  • 文档和帮助文本同步更新。
↑