第13章：OpenSCAD 源码架构与核心执行流程
1. 源码学习目标
学习 OpenSCAD 源码的目标不是立刻修改几何内核，而是理解脚本如何变成模型：源码文件如何组织，语言如何解析，模块如何求值，CSG 如何表示，预览和渲染如何分流，导入导出如何接入。
官方仓库显示源码主要在 src 下，包含 core、geometry、io、gui、glview、platform、utils 等目录，并有 openscad.cc、openscad_gui.cc 作为命令行和 GUI 入口相关文件。
2. 总体分层
可按以下方式理解：
- 入口层：解析命令行参数，决定 GUI、命令行导出、测试或特殊模式。
- 语言层：读取
.scad文件，词法/语法解析，构建 AST。 - 求值层：处理变量、函数、模块、作用域、include/use、children。
- CSG 层：把模块调用变成 CSG 节点树。
- 几何层：将 CSG 转换为可显示或可导出的几何表示。
- 渲染层：OpenCSG/OpenGL 预览或 CGAL 等精确几何计算。
- IO 层：导入导出 STL、OFF、DXF、SVG、PNG 等格式。
- GUI 层：编辑器、视图、菜单、参数、控制台、设置和用户交互。
3. core 目录
src/core 是语言和模型语义的核心。结合文件命名可看到 AST、表达式、上下文、模块、函数、内置能力、CSG 节点等内容。阅读顺序建议：
- 从 AST 和表达式类理解脚本结构如何表示。
- 阅读上下文和作用域实现，理解变量与参数解析。
- 阅读模块和函数相关代码，理解调用、默认值和 children。
- 阅读内置模块注册，了解 cube、sphere、translate、difference 等如何映射。
- 阅读 CSG 节点结构，理解几何树如何建立。
修改 core 时风险较高，因为语言行为会影响所有模型。
4. geometry 目录
src/geometry 处理二维、三维几何和后端算法。这里可能涉及多边形、网格、CGAL、Clipper、manifold、偏移、布尔和转换。学习重点：
- OpenSCAD 内部如何表示 2D 与 3D 几何。
- 预览几何与最终渲染几何有何差异。
- 多边形、网格、面片、法线、闭合性如何维护。
- CGAL 或其他几何库的调用边界在哪里。
- 错误、警告和退化几何如何传播到用户。
几何层通常是最复杂、最需要测试的部分。
5. io 目录
src/io 负责文件格式导入导出。阅读 IO 层时可按格式分类：
- 网格格式：STL、OFF、3MF、AMF 等。
- 二维格式：DXF、SVG。
- 图片输出：PNG 等。
- 文件路径、资源、缓存和依赖追踪。
导入导出修改通常需要准备真实样例文件，并同时测试 GUI 和命令行路径。
6. gui 与 glview
src/gui 负责 Qt 图形界面，包括主窗口、编辑器、偏好设置、控制台、参数面板和操作命令。src/glview 更关注三维视图、相机、OpenGL 渲染、选择和显示。
GUI 开发应注意：
- 不要把几何核心逻辑写死在界面层。
- 长时间渲染不能阻塞用户反馈。
- 错误信息要能从核心层传到控制台或状态栏。
- 设置项要兼容旧配置。
- 跨平台快捷键、字体和 OpenGL 能力存在差异。
7. 命令行入口
OpenSCAD 的命令行能力是自动化的基础。src/openscad.cc 等入口文件通常负责参数解析、输入输出路径、导出格式、变量覆盖、相机/图片参数和错误码。
阅读命令行实现时关注：
-o如何推断导出格式。-D如何传给语言求值层。- GUI 与 headless 路径如何分离。
- 导出失败时错误码是否正确。
- 日志和 warning 如何输出。
8. 从脚本到模型的流程
可以把执行流程简化为：
.scad 文件-> 词法/语法解析-> AST-> 上下文求值-> 模块实例化-> CSG 树-> 预览渲染或精确渲染-> 几何对象-> 导出文件或 GUI 显示
调试源码时应先确定问题发生在哪一层。例如：语法报错属于解析层，变量值不对属于求值层，F5 正确 F6 错误多半属于几何/布尔层，STL 文件异常属于导出层。
9. 阅读源码的方法
- 从一个简单模型开始，例如
cube(10);。 - 在入口处观察命令行参数如何传入。
- 找到 cube 内置模块注册和实例化位置。
- 跟踪 CSG 节点生成。
- 比较 F5 和 F6 的调用路径。
- 最后观察 STL 导出如何遍历几何。
不要一开始从最大文件逐行阅读。以具体模型和具体问题为线索更有效。
10. 源码修改风险
- 语言兼容性：旧模型可能依赖历史行为。
- 几何稳定性：一个小改动可能影响大量回归图像。
- 跨平台：Qt、OpenGL、字体、路径在三大系统上差异明显。
- 性能：更精确的算法可能让常见模型变慢。
- 错误信息：开发者能理解的异常不一定适合用户。
因此修改源码必须配合测试和最小复现模型。