第16章：源码架构与二次开发

1. 官方源码结构

FreeCAD 官方仓库的 src 目录体现了核心架构：

src/Base：基础类型、异常、工具、数学、参数等。
src/App：文档、对象、属性、表达式、事务、重计算等应用核心。
src/Gui：主窗口、命令、视图、选择、任务面板、Qt 集成等。
src/Mod：工作台模块，例如 Part、PartDesign、Sketcher、TechDraw、Draft、BIM、CAM、Fem、Mesh、Surface 等。
src/Main：程序入口。
src/3rdParty、src/Ext：第三方或扩展支持。

这种结构体现 App/Gui 分离：无界面模式也能进行文档和几何处理；GUI 只是其中一层。

2. App 层

App 层是 FreeCAD 的数据模型核心。重要概念包括：

Document：文档容器。
DocumentObject：文档对象基类。
Property：属性系统。
Expression：表达式引擎。
Transaction：撤销/重做。
Recompute：依赖重计算。

理解 App 层有助于开发参数化对象和稳定脚本。对象应通过属性保存状态，而不是只在内存变量中保存。

3. Gui 层

Gui 层负责用户交互：

命令注册与执行。
工具栏和菜单。
3D 视图和 Coin3D 场景。
选择系统。
任务面板。
ViewProvider。

开发 GUI 时要考虑无界面环境。核心算法应能在 App 层运行，GUI 只负责输入和展示。

4. Mod 模块

src/Mod 下每个工作台通常有 App、Gui、资源、测试和初始化文件。官方仓库中可见模块包括 Assembly、BIM、CAM、Draft、Fem、Import、Material、Measure、Mesh、OpenSCAD、Part、PartDesign、Sketcher、Spreadsheet、Surface、TechDraw 等。

这说明 FreeCAD 的功能不是一个巨大单体，而是一组围绕共同文档模型协作的模块。

5. C++ 与 Python 的关系

FreeCAD 既使用 C++ 又深度集成 Python：

C++ 提供性能、核心对象、几何和 GUI 基础。
Python 提供快速扩展、脚本和大量工作台逻辑。
SWIG、PyCXX、PySide、Pivy 等技术连接 C++、Python、Qt 和 Coin3D。

开发者应根据需求选择层级：

自动化和业务工具：优先 Python。
性能敏感几何算法：考虑 C++。
自定义 GUI：Python + PySide 通常足够。
核心架构修改：需要 C++ 和完整构建测试。

6. 构建系统

顶层 CMake 配置读取 version.json，设置项目版本，并检测依赖。它包含编译器检查、构建选项初始化、模块依赖检查、LibPack、Doxygen、fmt、yaml-cpp、Python、OpenCASCADE、Qt、Coin3D、Pivy、Boost 等。

开发者应理解：

构建失败常由依赖版本不匹配引起。
GUI 构建比无界面构建依赖更多。
FEM、BIM、VR 等功能可能启用额外依赖。
开发测试需要 ENABLE_DEVELOPER_TESTS。

7. 贡献流程

官方 CONTRIBUTING.md 描述 FreeCAD Contribution Process。核心精神包括：

使用 GitHub Issue 和 Pull Request。
PR 应解决一个明确问题。
尽量避免不必要依赖。
每个提交应能编译。
不应破坏 Python API，若不可避免需清楚说明。
贡献必须满足许可证和版权要求。

即使只是插件开发，也应遵循类似原则：小步修改、清晰说明、可测试、尊重兼容性。

8. 阅读源码路线

推荐路线：

从 README 和 Developers Handbook 理解整体。
阅读 src/Mod/Sketcher、PartDesign、TechDraw 的目录结构。
查看某个简单 Python 工作台的 InitGui.py。
阅读 App 层 DocumentObject 和 Property 概念。
跟踪一个命令从 GUI 到对象创建的调用链。
用调试构建验证理解。

不要一开始试图读完整仓库。选择一个命令或对象作为切入点更有效。

9. 二次开发边界

修改 FreeCAD 核心源码成本高，需要跨平台构建和社区评审。很多需求可以通过插件完成。判断原则：

只服务本团队业务：插件。
可由 Python API 实现：插件或宏。
需要高性能或核心功能：C++ 模块。
影响大量用户和 API：提交上游 PR 前先讨论。