简介这是一份 FreeCAD 1.0 的完整源代码资源包适合 CAD 软件开发者、三维建模爱好者以及希望研究开源参数化设计实现的技术人员也可作为大型 C 工程的阅读范本。FreeCAD 是跨平台开源 CAD 软件代码以 C 为主并按 GPL 协议发布其模块化架构和工作台机制为功能定制提供了便利。资源共含 2000 个文件压缩包约 97.18MB其中以 C 源文件约 915 个 .cpp 与 754 个 .h为核心覆盖对象建模、图形渲染、导入导出等关键实现另有 Python 脚本、XML 配置、Markdown 文档及少量编译辅助文件便于阅读代码、理解构建流程和进行二次开发。代码从底层解析器到上层 Python 工具链呈现清晰分层可按需阅读特定模块目前已有 413 人浏览学习。通过这份源码可以深入 FreeCAD 的参数化对象系统、工作台扩展机制、STEP/DXF/STL 等格式接口还能参考示例脚本快速上手插件开发无论是学习大型 C 项目结构还是构建自有 CAD 工具链这份 1.0 版本源码都有较高的参考价值。1. FreeCAD 1.0 源代码为什么这个版本值得下下来拆一遍FreeCAD 1.0 源代码发布后CAD 方向的开发者和自动化脚本玩家基本都在讨论这个版本。相比早期版本1.0 最大的变化是 API 走向稳定、工作台框架统一文档对象模型和参数化约束引擎在架构上基本冻结这就意味着基于它做二次开发和工具链集成代码不会频繁被上游重构打乱。源码用 C 写底层、Python 做脚本接口整体体量在四十万行上下覆盖从参数化建模、装配到 Python API 和 GUI 层的全部实现。如果你打算自己扩展 CAD 功能、搞自动化出图或者定制界面这份源码就是最直接的参考比对着黑盒 API 盲试省力得多。这篇文章不准备夸功能只讲清楚源码获取、编译、验证、避坑这条实操路线上的关键动作。2. 源码获取与项目结构先从顶层看懂这个代码库拿到一份源码工程不能一头扎进某个 .cpp 文件里翻那是把力气花错了地方。FreeCAD 1.0 的源码组织方式很清晰先用十分钟把顶层结构扫一遍后面无论是找入口函数还是定位崩溃挂在哪里都能按图索骥。2.1 源码获取方式与分支选择逻辑最稳妥的获取方式是直接克隆官方仓库。但要注意分支选择直接拉默认分支拿到的通常是处于活跃开发状态的代码API 变动频繁不适合作为学习或二次开发基线。我的习惯是拉取 release 标签版本对应 1.0 正式发布时的代码快照经过完整回归测试编译成功率和稳定性都远高于开发分支。git clone https://github.com/FreeCAD/FreeCAD.git cd FreeCAD git checkout 1.0 git submodule update --init --recursive这里几个步骤分别说明克隆时如果不加--depth参数会拉取完整历史仓库体量不小磁盘紧张可以加上--depth1只取最新快照checkout 到标签版本是让工作区代码与 1.0 发布时刻保持一致submodule 的初始化很关键FreeCAD 使用了第三方依赖子模块不执行这一步后续配置 CMake 时一定会报缺失路径。另外提醒一句直接拉默认分支再切回 1.0 标签有时会因为缓存不干净产生陈旧文件遇到诡异编译错误时删掉整个目录重新克隆反而更快别舍不得那点下载时间。2.2 顶层目录划分App、GUI、Base、Mod 四个核心FreeCAD 1.0 源码顶层目录不少但真正核心的就四个。目录职责说明src/Base基础工具类库提供类型、容器、数学工具、配置读写、XML 解析等底层能力是所有模块的公共地基src/App应用框架与文档对象模型管理文档、视图、对象生命周期核心是Document、DocumentObject、Property体系src/GUI图形界面框架基于 Qt 构建负责主窗口、工作台切换、视图控制、命令注册与路由src/Mod功能模块工作台按领域划分Part、PartDesign、Sketcher、Assembly等每个都是独立插件这四个目录的关系可以这样理解Base 是最底层的地基App 在 Base 之上构建出文档对象模型GUI 在 App 之上提供交互界面而 Mod 里的每个工作台是把对象模型和用户命令黏合起来的具体业务实现。写二次开发代码时大部分场景只要跟 App 和 Mod 打交道Base 在特殊需求下才需要深度介入。src/Mod内部也有层次。以最常见的Part为例目录里包含App子目录存放核心 C 对象实现Gui子目录存放命令和视图交互。而PartDesign这类更上层的工作台则是依赖 Part 的几何内核接口再做约束与特征操作。调试时如果遇到功能不生效的怪问题先确认你改的代码所在的抽象层次对不对。2.3 用 Python 接口快速验证核心对象模型FreeCAD 1.0 编译好后自带 Python 解释器可以通过命令行直接进交互环境。这一步看起来简单但它是验证整套对象模型是否正常工作的最快捷路径。import FreeCAD doc FreeCAD.newDocument(test) obj doc.addObject(Part::Box, MyBox) obj.Length 20 obj.Width 15 obj.Height 10 doc.recompute() print(Volume: , obj.Shape.Volume)这段脚本做的事情很直接创建一份新文档在里面加了一个 20×15×10 的立方体盒子重新计算后输出体积。addObject的第一个参数Part::Box是类型标识符第二个参数是对象在文档树里的名字改参数后需要调用doc.recompute()否则依赖关系链上的对象不会自动更新。如果这段脚本执行流畅没有报错说明编译产物完整Base、App、Part 模块之间的链接没有问题。3. 编译 FreeCAD 1.0CMake 参数配置与实操步骤源码拿到了下一步是编译。编译这一步卡住了很多人问题是依赖版本和 CMake 选项组合方式五花八门。把思路理清楚按顺序操作成功率高得多。3.1 依赖准备清单与版本对应关系先列出 FreeCAD 1.0 编译时最关键的几个依赖库及其版本约束。依赖库建议版本在编译中的角色OpenCASCADE7.4.0 及以上几何内核所有 Part 相关的布尔运算、曲面和实体操作都由它提供Qt5.12 以上或 Qt 6.xGUI 层依赖1.0 版本对 Qt6 的支持已较完善Python3.8 及以上脚本接口与模块系统基石CMake3.12 以上构建系统生成器Boost1.70 以上C 基础库主要在 App 层使用编译器GCC 9 / MSVC 2019C17 标准支持必须到位OpenCASCADE 是这里最重要的一个它也是 FreeCAD 依赖中唯一一个让很多人直接劝退的库。上一节里提到的子模块更新实际上就包含了 OCC 相关的对接信息但 OCC 本体往往需要单独安装。在 Linux 下最省事的方式是直接用发行版的系统包管理器装 OCC 开发包版本对应关系通常被维护得比较好。进入 CMake 配置后如果检测不到 OCC绝大部分原因是它的安装路径不在 CMake 默认搜索范围里。3.2 CMake 配置命令与关键开关说明CMake 配置是整个编译过程的分水岭。配置选项设置得过少构建时缺功能设置得太多编译时间和依赖冲突的几率同步上升。直接用一套典型配置起步选项含义逐项说清楚。cmake -G Unix Makefiles \ -DCMAKE_BUILD_TYPERelease \ -DBUILD_QT6ON \ -DFREECAD_USE_PIPOFF \ -DFREECAD_USE_QT_OPENGLON \ -DFREECAD_BUILD_ASSEMBLYON \ -DFREECAD_BUILD_CAMOFF \ -DPYTHON_EXECUTABLE/usr/bin/python3 \ ../FreeCAD这一串命令里值得展开说的几个点-DBUILD_QT6ON表示使用 Qt6 构建 GUI 层。如果是老机器上只有 Qt5 环境这一项的值要改成 OFF同时得保证系统里安装了对应的 Qt5 开发包。同一套源码里 Qt5 和 Qt6 的 GUI 封装有差异在这里选错会导致预编译头文件报错。-DFREECAD_USE_PIPOFF关闭通过 pip 自动安装 Python 依赖的机制。自动装包省事但不透明装坏后很难排查所以一般建议手动准备依赖环境保持构建可复现。-DFREECAD_BUILD_ASSEMBLYON开启装配工作台的构建-DFREECAD_BUILD_CAMOFF关闭 CAM计算辅助制造模块。1.0 版本里 CAM 模块虽然可用但体量较大编译时间明显偏长如果不需要做加工轨迹生成就先关掉它。3.3 编译过程与运行方式CMake 配置通过后进入实际编译阶段。这里要特意强调别一上来就全核并行编译。FreeCAD 源码里有些文件相互依赖极强全核并行会让链接器内存吃掉几个 GB8GB 内存的机器经常直接崩掉。make -j4-j4这个参数不建议盲目调高四核并行是内存消耗和编译时间之间比较平衡的点。编译完成后运行目录下的可执行文件即可验证。./bin/FreeCAD如果 GUI 界面正常起来能任意创建文档和绘制模型说明整套编译链路已经打通。如果这一步只是拿到命令行界面没有出现窗口那就退回到检查 Qt 相关配置项问题多半出在 Qt 库链接路径上。4. 避坑编译源码时最典型的五类问题与排查记录FreeCAD 1.0 编译过程中的坑说来说去就集中在几个固定位置。把最常见的情况总结成现象、原因、解决三个步骤遇到时可以少走冤枉路。4.1 现象OpenCASCADE 版本过低导致 Part 模块启动即崩溃编译过程没有报错但运行后只要一切到 Part 工作台程序直接闪退没有任何提示框。原因是 OpenCASCADE 的版本低于 FreeCAD 1.0 的最低要求。几何内核接口有前置条件版本不满足时Part 模块初始化阶段调用 OCC 的底层 API 就直接中断。解决方式也很直白先检查 OCC 版本号然后升级到 7.4.0 以上的版本。occ_version$(python3 -c import OCC; print(OCC.VERSION) 2/dev/null || echo not found) echo $occ_version版本如果显示 not found 或者版本号确实偏旧在 Linux 下挂载较新版本源或手动编译 OCC 是常见做法。手动编译 OCC 耗时较长但能保证和 FreeCAD 源码的对齐关系值得花这个时间。4.2 现象Python 模块导入失败报错找不到 FreeCAD 模块名运行python3 -c import FreeCAD直接抛 ModuleNotFoundError但编译过程明明没有报错。原因是 FreeCAD 编译产物的 Python 模块路径不在 Python 解释器的搜索范围内。FreeCAD 的 Python 绑定不会装到系统全局 Python 目录里需要把编译产物的lib路径加进PYTHONPATH环境变量。解决方法是编辑当前 shell 的环境变量或者更持久地写进配置文件。export PYTHONPATH/path/to/FreeCAD-build/lib:/path/to/FreeCAD-build/lib/python这里的关键是路径下存在FreeCAD.so或FreeCAD.dll之类的核心绑定文件。设置完成后重新启动 Python 解释器再试。如果你在 IDE 里开发注意 IDE 的虚拟环境也要同步设置同样的环境变量不然 GUI 里测试正常IDE 里一跑就找不到模块。4.3 现象编译到一半报错提示内存不足同样的源码和命令在同事的机器上编译通过了自己的机器编译到一半直接被系统 OOM 杀掉没有任何具体错误定位就是 make 进程消失。原因是链接阶段多个目标文件同时链接占用了大量内存。综合来看是make -j并行度设置不合理或者系统 swap 空间配置不足。解决方式分两步第一步降低并行度make -j2把并行度降一半大部分内存问题立刻缓解第二步检查 swap 空间如果 swap 本身为零建议至少分配和物理内存等同大小的 swap 容量。make -j2这一步在 8GB 内存的虚拟机上实测有效编译时间大概会比四核慢三成但能稳定编译完。4.4 现象GUI 界面文字显示异常菜单出现方块乱码编译顺利启动成功但菜单项全是乱码方块或者按钮上的文字挤成一团完全看不出含义。原因是 FreeCAD 的 GUI 层在寻找翻译文件和字体时路径不正确。1.0 版本中语言文件路径是相对于二进制所在地的相对路径如果运行时没有从正确的目录启动就会导致资源找不到。解决方式也很简单不要通过快捷方式或软链接启动而是回到编译目录用相对路径直接运行./bin/FreeCAD或者把工作目录切到编译根目录后再运行。4.5 现象CMake 重新配置后某些模块消失第一次配置还好的加了几个选项再重新 CMake某个工作台模块在构建列表里消失了。原因是 CMake 配置变更后旧版本的 CMakeCache 中残留了一些模块开关状态新配置不会自动刷新已缓存的选项。解决方式是清空 CMakeCache重新配置。rm -rf CMakeCache.txt CMakeFiles cmake -G Unix Makefiles ../FreeCAD这里要注意删除的是构建目录中的缓存不是源码目录里的任何文件。删错了地方会把源码目录弄乱重新配置会变得一团糟。5. 二次开发入门从源码读懂一条指令的完整执行链源码拿到手坑也都避过了真正有价值的部分才刚开始理解 FreeCAD 的运行机制并在此基础上做自定义开发。这一章从一条最基础的创建盒子命令入手把从 GUI 点击动作到 C 对象落地的完整链路串起来。5.1 命令入口从 Python 命令到 C 对象FreeCAD 中在执行addObject(Part::Box)时GUI 层和 App 层之间必然有一个命令分发的过程。源码里查这个流程有个固定的入口。grep -r Part::Box src/Mod/Part --include*.cpp --include*.py -n这条命令的执行目的是在src/Mod/Part目录下找出所有注册了Part::Box类型的文件。查到的文件通常包括两个部分一个在Part模块的 App 目录里负责定义对象的 C 类型一个在 Gui 目录里负责定义该类型在 GUI 侧的显示策略。这条链路点明了一个核心设计FreeCAD 的对象创建走的是工厂注册模式Python 层的addObject根据字符串参数在注册表里找到对应的 C 创建函数然后实例化对象。深入理解这个机制是后面所有修修改改的基础。FreeCAD 1.0 的官方文档里把每个工作台都称为一个模块就是这个原因它本质上不是一个单体的 CAD 软件而是一个模块化框架。5.2 修改源码做最小实验添加一个自定义属性在动手做大改造之前先做个小实验在已有对象上加一个自定义属性。从源码来说属性是被绑定在对象定义里的字段修改对象定义需要重新编译对应模块。找到src/Mod/Part/App/BoxFeature.cpp或对应源码在初始化函数中可以看到属性注册调用。模仿同类属性写一行注册代码。void Box::onChanged(const App::Property* prop) { App::GeoFeature::onChanged(prop); // 这里可以自定义属性变更时的处理逻辑 }这种做法是最小代价理解 FreeCAD 对象属性体系的入口。改完编译后通过 Python 侧调用就能检查属性是否生效。obj doc.addObject(Part::Box, Box) obj.addProperty(App::PropertyLength, MyLength, Custom, 测试自定义属性长度) obj.MyLength 50addProperty的第一个参数是属性类型第二个参数是属性名称第三个参数是所属分组第四个参数是描述文字。自定义属性加进来后可以像内置属性一样读写和参与 recompute。这一步唯一要记住的是在你没摸清楚工程构建体系之前不要用生成器新建项目来改 FreeCAD 源码一定要在现有 CMake 工程里直接改、直接编译否则依赖关系会错乱。5.3 源码调试常用日志断点位置改完代码后如果行为不对需要直接在源码中插入日志输出。FreeCAD 源码里内置了一套日志宏最好的插桩位点是对象初始化和 recompute 的两个核心函数。// 在关键计算函数入口处插入 Base::Console().Message(MyDebug: Box recompute entered\n); Base::Console().Warning(MyDebug: width is %f\n, this-Width.getValue());上面第一种输出普通信息第二种输出警告信息。编译运行后这些信息会出现在当前视图的“视图-输出面板”中。通过对这些日志点的观察你可以看清目标函数的调用时序确认是哪一层调用出了问题。在二次开发中遇到玄学问题时这套机制是定位问题的第一选择。6. 验证源码可靠性与做轻量定制的几条高效路径源码编译完、跑通了也认清了模块架构接着就要回到一个更实际的问题这套源码能不能被验证、能不能做出自己的功能。FreeCAD 1.0 最好的地方在于自带的 Python API 几乎暴露了全部底层对象能力验证源码时不需要总是回到 C 重编译的老路上去。我对源码级验证的操作习惯是这样的先把现有的 Python API 当成一个“检查器”用一段脚本遍历文件系统里的模型检查对象的有效性看有没有几何数据坏掉。import FreeCAD import Part doc FreeCAD.openDocument(/path/to/model.FCStd) for obj in doc.Objects: if hasattr(obj, Shape) and obj.Shape.isNull() False: print(obj.Name, solid:, obj.Shape.Solid) else: print(obj.Name, has no valid shape)这段脚本把文档里所有对象都过一遍检查形状是否有效。源码层面的实现逻辑、属性更新机制是否可靠通过大量对象样本跑一遍就能得到非常直观的结论。如果对象的 shape 数据大面积报错那不是用法问题而是编译时几何内核对接有缺陷应该回到 OCC 版本验证上排查。验证完源码可靠性之后再谈定制。1.0 里最实用的轻量定制路径是添加自定义工作台。不用改核心源码只需要在 Mod 目录下建一个 Python 包用 FreeCAD 的InitGui.py机制注册命令。这个方案的好处是被限制在 Python 层不碰 C 编译流程只要 API 调用正确就能热加载。几个月前我在一个需要批量处理图纸的项目里就是这么干的建了一个内部模块通过addCommand注册批量导出函数在用户菜单里增加了一个按钮整个过程没有改一行 C 代码。从那以后我每次拿到一套新源码都会强制自己先走一遍“编译 — Python API 验证 — 轻量定制注册”这个流程验证编译产物可用之后再动手深度改 C 层这套顺序救了我好几次希望也能帮到你。本文还有配套的精品资源点击获取