第02章：安装、环境配置与开发工作流

1. 安装方式概览

OpenSCAD 可运行在 Linux/UNIX、Windows 和 macOS。普通学习者优先安装官方二进制版本；需要跟踪新功能、修复 bug 或研究源码时再从源代码构建。官方 README 指向 https://www.openscad.org/downloads.html 获取安装包。

常见安装方式包括：

• Windows：下载安装包或便携包，安装后可通过图形界面或命令行调用 openscad.exe。
• macOS：下载 .dmg，也可通过 Homebrew 安装；源码构建需要 Xcode 和 Homebrew 依赖。
• Linux：发行版仓库通常提供稳定版本；也可使用 AppImage、Flatpak、Snap 或源码构建。
• Nix：官方仓库包含 Nix 开发 shell，适合隔离式构建。
• WebAssembly：官方仓库支持 headless wasm 构建，适合浏览器或 Node 集成。

2. 图形界面初识

打开 OpenSCAD 后通常会看到脚本编辑区、三维视图区、控制台输出区和菜单工具栏。基本工作流是：

1. 在编辑区写 .scad 脚本。
2. 按 F5 执行预览，快速检查 CSG 结构和形状。
3. 按 F6 执行完整渲染，得到可导出的真实网格。
4. 使用导出命令保存 STL、OFF、3MF、AMF、SVG、DXF、PNG 等格式。
5. 根据控制台警告修复非流形、空对象、参数错误或渲染过慢问题。

F5 与 F6 是理解 OpenSCAD 的关键。F5 更像快速图形预览，依赖 OpenCSG 等机制，可交互但不一定生成最终网格。F6 会进行真实几何计算，通常更慢，但用于导出制造文件。

3. 第一个模型

下面是最小模型：

cube([20, 10, 5], center = true);

这个模型创建一个居中的长方体。将其扩展成带孔支架：

$fn = 64;

length = 60;
width = 20;
thickness = 6;
hole_d = 5;

module rounded_slot_body() {
    hull() {
        translate([-length/2 + width/2, 0, 0]) cylinder(h = thickness, d = width, center = true);
        translate([ length/2 - width/2, 0, 0]) cylinder(h = thickness, d = width, center = true);
    }
}

difference() {
    rounded_slot_body();
    for (x = [-20, 20])
        translate([x, 0, 0]) cylinder(h = thickness + 1, d = hole_d, center = true);
}

这个例子已经体现了 OpenSCAD 的核心：参数、模块、循环、变换、基本体、布尔差集和圆弧分辨率。

4. 命令行基础

OpenSCAD 可以作为命令行工具使用。常见命令形式：

openscad -o output.stl model.scad
openscad -o preview.png --imgsize=1200,800 model.scad
openscad -D 'width=80' -D 'height=30' -o bracket_80x30.stl bracket.scad

命令行适合批量导出、自动测试和 CI。-D 会在命令行覆盖变量，适合生成不同规格。实际项目中建议把导出命令写入 Makefile、justfile、Shell 脚本或 CI 流程。

5. 项目目录建议

一个中等规模 OpenSCAD 项目可以这样组织：

project/
  src/
    main.scad
    parts/
      bracket.scad
      cover.scad
    lib/
      fasteners.scad
      math.scad
  variants/
    small.scad
    large.scad
  exports/
    stl/
    png/
  docs/
    assembly.md

建议：

• src/main.scad 只做装配和总入口。
• 复用模块放在 src/lib 或 src/parts。
• 变量文件按产品规格分开放置。
• 导出文件不要和源文件混在一起。
• 使用 Git 跟踪 .scad、说明文档和少量关键预览图；大批量导出网格可按需要忽略。

6. 编辑器配置

除了内置编辑器，也可以使用 VS Code、Vim、Emacs 等编辑 .scad 文件。建议配置：

• OpenSCAD 语法高亮。
• 保存时保留空格缩进，常用 2 或 4 空格。
• 文件末尾换行。
• 项目统一单位，通常默认把数值当作毫米。
• 代码块花括号位置保持一致。
• 复杂模型用注释分区，但不要用注释隐藏过期参数。

7. 源码构建环境

如果要构建 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 等。

Linux/BSD 上可使用仓库脚本辅助安装依赖：

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

不同平台依赖差异很大，学习源码时不必一开始就完整打包发布版本。先完成 Debug 构建、运行单元测试和命令行导出，是更实际的目标。

8. 日常开发工作流

对于模型开发：

1. 写最小可运行模块。
2. 用 F5 快速预览结构。
3. 用颜色和透明度检查内部关系。
4. 用 F6 验证最终几何。
5. 导出 STL 并用切片软件检查体积、面片和支撑。
6. 打印小样，测量误差，回填参数。

对于 OpenSCAD 源码开发：

1. 从 issue 或小功能开始，不要一开始改几何核心。
2. 建立可复现 .scad 示例和测试。
3. 在核心层、GUI 层、IO 层之间保持边界清晰。
4. 修改语言行为时同时更新测试和文档。
5. 使用 Debug 构建观察 AST、CSG、Geometry、导出阶段。