前言
CAD 软件、特别是三维CAD，无论大小，都要面对同一组问题：对象如何表达，属性如何编辑，文件如何保存与恢复，修改如何撤销，用户操作如何统一管理。本文不写使用教程，不做逐行源码导读，也不提供现成案例，只想借一个开源、可阅读、可调试的完整平台，把这些难题拆成可理解的设计问题，看它如何逐个作答。
在使用 FreeCAD 时，我们很容易把界面上的操作当成理所当然：创建一个对象，它出现在模型树里；选中它，特性面板显示出参数；修改一个属性，三维视图随之更新；按下 Ctrl+Z，刚才的修改被撤销；保存文件，下次打开后一切仍在。对普通用户来说，这些只是日常操作。但对软件开发者来说，这背后其实是一套相当完整的文档对象系统。
这个系列准备从源码角度解读 FreeCAD 的核心机制。我们关心的不是某个功能怎么用，而是另一个问题：FreeCAD 是如何把一个 C++ 或 Python 对象，变成一个可显示、可编辑、可保存、可恢复、可撤销、可宏记录的 CAD 文档对象的？
本章先给出全局的总览，具体机制将在后续章节逐一展开。
本系列的组织结构
本系列共分为7章，其主要内容如下。
- 第一章：介绍 FreeCAD 的整体架构。 从 Application 入手，分析它如何管理文档、模块、界面和命令，并说明 Base、App、Gui 三层的分工。
- 第二章：介绍 Property 属性系统。 说明 FreeCAD 如何用统一的属性模型表达对象数据，并为保存、撤销、界面编辑和重算提供基础。
- 第三章： 介绍动态属性与特性面板。 分析属性如何在运行时添加，以及特性面板如何根据属性类型自动生成编辑界面。
- 第四章： 介绍 FreeCAD 的文档对象模型。 分析 Document 如何管理 DocumentObject 的创建、命名、依赖和重算流程。
- 第五章：介绍 FreeCAD 的显示层。 说明 ViewProvider 如何把 DocumentObject 转换为 Coin3D 场景节点，三维选择如何从场景节点反查文档对象，以及对象属性或显示属性变化后如何刷新三维显示。
- 第六章：介绍 FCStd 文件格式。 分析 FreeCAD 文件如何保存与恢复，包括 Document.xml、GuiDocument.xml 和压缩包内其他数据文件。
- 第七章： 介绍事务与 Undo/Redo。 说明属性修改、对象创建删除和动态属性变化如何被记录，以及撤销重做机制的实现原理。
- 第八章： 介绍 Command 与 Action。 分析菜单、工具栏、快捷键和 Python 脚本为什么能触发同一操作，以及命令如何与事务、宏记录和界面更新配合。
- 附录 图表、术语、实验
FreeCAD的安装与调试
作为一款功能完整且持续演进的开源CAD平台，FreeCAD的安装与调试路径有其自身的特点。FreeCAD是一个完整的CAD应用，编译产物包含核心库、Gui模块、工作台以及Python绑定，调试入口也因是否加载图形界面而分为多个可执行目标。本章力求帮助读者从原理上理解FreeCAD的获取与编译方法，掌握CMake与LibPack的配合使用，建立开发环境并生成第一个可运行的FreeCAD程序，以及了解最常用的命令行调试与回溯方法。
快速安装与使用
下载预编译包
FreeCAD提供了官方维护的安装包，覆盖Windows、Linux和macOS三大平台。官方下载页面为：https://wiki.freecad.org/Download，Windows用户可下载`.msi`安装包，Debian/Ubuntu用户可使用`.deb`包或通过发行版的包管理器获取，openSUSE用户使用`.rpm`包，Linux用户还可以直接运行独立的AppImage可执行文件，无需安装即可体验。对于只想快速了解FreeCAD界面和基本操作的读者，预编译包是最直接的选择。
以windows版本为例，当前最新的预编译包为FreeCAD 1.1.4，于 2026 年 9 月 28 日发布。
软件界面介绍
安装完成后启动FreeCAD，会看到启动页。界面被划 分为若干区域：中央是3D视图，左侧是树视图（显示文档中对象的层次结构和构造历史），其下方是属性编辑器，底部是报告视图和Python控制台，顶部是工作台选择器。FreeCAD的核心组织概念是工作台（Workbench），每个工作台是一组面向特定任务的工具集合，例如Part Design用于基于草图的实体建模，Sketcher用于约束草图绘制，Draft用于2D绘图。用户通过工作台选择器切换当前工作台，也可以在首选项中设置默认工作台。
FreeCAD的3D视图操控逻辑有其特定的导航模式。默认的"CAD操作"模式通过鼠标中键、右键和滚轮的组合完成平移、旋转和缩放。预设视图（顶视图、前视图等）可通过视图菜单、工具栏或数字快捷键（1、2等）快速切换。
然而，预编译包并不能满足本系列的目标。我们需要的是可阅读、可调试的源码。因此，快速安装与使用只是验证环境是否就绪的第一步，接下来的源码编译与调试才是真正进入FreeCAD内部机制的入口。
从源码编译与调试
从源码编译FreeCAD的过程比较复杂。它的依赖涵盖OpenCascade几何内核、Coin3D场景图、Qt界面框架、Python解释器、Boost、Eigen、VTK等数十个组件。这些依赖的版本匹配和路径配置，是编译过程中最耗时的环节。
FreeCAD官方为Windows用户提供了LibPack，将大部分依赖预先编译打包，大幅降低了配置难度。LibPack的版本需要与FreeCAD源码版本对应，下载后解压到任意位置，在CMake配置时通过FREECAD_LIBPACK_DIR变量指向该目录即可。对于Linux用户，依赖通常通过发行版的包管理器安装，FreeCAD文档列出了Debian/Ubuntu下所需的完整包列表，涵盖OpenCascade、Coin3D、Qt5、Python3、Boost等。
源码获取可使用Git，并携带子模块，如果网络条件受限，也可以在GitHub页面下载对应版本的源码压缩包。
bash
git clone --recurse-submodules https://github.com/FreeCAD/FreeCAD.gitCMake配置是编译的核心步骤。在CMake GUI中，将源码路径指向FreeCAD根目录，构建路径指向一个独立的空目录（out-of-source构建）。点击Configure后选择对应的生成器（Windows下通常为Visual Studio版本，Linux下为Unix Makefiles或Ninja）。
|----------------------------------------------------------------------------|
| 
|
| CMake-gui主界面 |
|----------------------------------------------------------------------------|
| 
|
| 生成器配置界面 |
| 
|
| 可选的生成器 |
关键的配置变量包括：FREECAD_LIBPACK_DIR(Windows指向LibPack目录)、CMAKE_INSTALL_PREFIX(安装路径)。如果计划直接从构建目录运行调试，建议启用FREECAD_COPY_DEPEND_DIRS_TO_BUILD、FREECAD_COPY_LIBPACK_BIN_TO_BUILD和FREECAD_COPY_PLUGINS_BIN_TO_BUILD，这三个选项会将运行所需的动态库和Qt插件复制到构建输出目录，避免调试时因找不到DLL而无法启动。
配置通过后，生成工程文件。Windows用户打开FreeCAD.sln，先编译ALL_BUILD目标，再编译INSTALL目标以完成安装。编译时间取决于机器性能，通常在半小时到数小时之间。Linux用户执行make -j$(nproc)和make install即可。
编译完成后的调试入口，是我们进入源码阅读的起点。FreeCAD提供了多个可执行目标，对应不同的运行切面。Windows下在Visual Studio中右键设置启动项目，Linux下则直接运行对应的二进制文件。
FreeCADMain 是完整的图形界面入口。它初始化Base、App和Gui三层，加载工作台、启动主窗口、挂接Coin3D渲染场景。本系列后续追踪的核心链路------DocumentObject的创建、ViewProvider的挂接、特性面板的响应、事务入栈与宏记录------只有在FreeCADMain下才能在同一进程内完整观察。因此，本系列的调试将以FreeCADMain为主视角。在Visual Studio中，将FreeCADMain设为启动项目后，可以直接按F5进入调试，在源码中设置断点，观察属性系统的初始化、文档对象的构造以及Gui层的响应过程。
FreeCADMainCmd 是无头命令行入口。它初始化Base和App，执行各模块的Init.py，但不加载InitGui.py，因此Gui层完全不会被加载。这个入口适合单独验证App层的行为，例如文档的创建、属性的序列化、事务的提交与撤销，而不受界面逻辑的干扰。命令行版本还提供了一系列调试选项：-l或--write-log将日志写入文件，--log-file指定任意日志路径，-c或--console以控制台模式启动，-t或--run-test执行测试用例。这些选项在定位启动阶段的配置问题时尤为有用。
FreeCADMainPy 或相关的Python嵌入目标，则将FreeCAD作为模块暴露给外部Python解释器。其入口不是main()，而是模块初始化函数。适用于将FreeCAD的文档系统和几何内核嵌入自定义脚本、Jupyter笔记本或自动化测试流程的场景。对于研究Property和Document在Python侧的暴露方式，这个入口提供了直接的观察窗口。
调试过程中，如果遇到崩溃，生成回溯（backtrace）是定位问题的标准手段。Linux下使用gdb运行FreeCAD，执行bt或bt full可打印调用栈和局部变量。macOS下使用lldb，步骤类似。Windows下Visual Studio在调试模式下会自动在崩溃时中断，可直接查看调用栈和变量值。FreeCAD官方文档还建议在报告问题前先运行测试框架，确认是否为已知的安装或依赖问题。
还有一个值得留意的编译选项：FREECAD_RELEASE_PDB。在Release构建中同时生成PDB调试符号文件，可以在不牺牲运行速度的前提下，在崩溃时获得函数名和行号信息。对于需要分析Release版本中偶发崩溃的读者，这个选项比完整的Debug构建更为实用。
至此，我们已经完成了从获取FreeCAD、编译源码到选择调试入口的完整准备。下一章将正式进入Base/App/Gui三层架构，从这张地图开始，逐层拆解FreeCAD如何用一套统一的机制，把C++/Python对象变成可显示、可保存、可撤销、可宏记录的CAD文档对象。
文末
阅读源码的目的不止于了解"它怎么实现"，更在于理解"CAD软件为什么这样设计"，进而判断哪些机制可以借鉴到自己的工程实践中。这不是纯粹的源码导览，也不是FreeCAD使用教程，而是一次以源码为基础的软件设计学习：把实现拆成可理解的设计问题------数据如何表达，界面如何动态生成，文件如何保存，修改如何撤销，用户操作如何统一入口。
这个过程也是一次持续挖掘的旅程。每弄清一层机制，都可能带来意料之外的发现与惊喜，而这些积累最终指向一个更远的目标：为将来开发自己的系统打下基础。所得未必渺小，它可能正是一个新作品的开端。