LightWork3D/docs/FreeCAD Windows 编译运行指南.md

# FreeCAD Windows 编译运行傻瓜指南

这份文档面向第一次在 Windows 上编译 FreeCAD 的同学。

目标是：

- 不改源码
- 用 Visual Studio 2022 成功编译
- 能在本机直接运行 FreeCAD
- 能在 VS 里按 `F5` 调试

本文档基于下面这套已经验证成功的组合：

- 源码分支：`releases/FreeCAD-1-1`
- 源码版本：`1.1.1-28-g94f4cb77f6`
- 编译器：Visual Studio 2022
- 构建配置：`RelWithDebInfo | x64`
- LibPack：`LibPack-1.1.0-v3.1.1.3-Release`

## 1. 先理解三个目录

编译 FreeCAD 时，最好把“源码目录”“构建目录”“运行目录”分开。

建议按下面这样放：

```text
D:\project\LightWork3D\FreeCAD                    源码目录
E:\fc\LibPack-1.1.0-v3.1.1.3-Release             依赖目录
E:\fc\build-relwithdebinfo-libpack3113           构建目录
E:\fc\run-FreeCAD-1.1.1                          安装后的运行目录
```

不要把所有东西都堆在一个目录里。

## 2. 需要安装的软件

至少准备好这些：

1. `Visual Studio 2022`
2. `Desktop development with C++` 工作负载
3. `CMake`
4. `Git`

建议：

- 用 64 位系统
- `E:` 盘最好预留 100GB 以上
- `C:` 和 `D:` 至少各留 30GB 可用空间

## 3. 下载源码

把 FreeCAD 源码放到：

```text
D:\project\LightWork3D\FreeCAD
```

如果你已经有源码，确认当前分支是：

```powershell
git -C D:\project\LightWork3D\FreeCAD rev-parse --abbrev-ref HEAD
```

应该看到：

```text
releases/FreeCAD-1-1
```

## 4. 下载完全匹配的 LibPack

这一步非常重要。

对于这份源码，不要随便换别的 LibPack。已经验证成功的是：

[LibPack-1.1.0-v3.1.1.3-Release.7z](https://github.com/FreeCAD/FreeCAD-LibPack/releases/download/3.1.1.3/LibPack-1.1.0-v3.1.1.3-Release.7z)

下载后解压到：

```text
E:\fc\LibPack-1.1.0-v3.1.1.3-Release
```

不要用 `3.1.1.2`。  
这份源码配 `3.1.1.2` 时，已经实测会在链接阶段报 `boost::program_options ... contains` 相关错误。

## 5. 清理磁盘空间

如果你之前编过很多次，建议先清理旧构建目录。

重点清理这些“可再生目录”：

```text
旧 build 目录
旧 LibPack 目录
下载缓存
C:\Users\<你的用户名>\AppData\Local\Temp
C:\Windows\Temp
```

如果你在编译中看到下面这些错误：

```text
No space left on device
磁盘空间不足
无法创建目录
```

那不是源码问题，就是磁盘满了。

## 6. 新建构建目录

在 `E:` 盘新建目录：

```text
E:\fc\build-relwithdebinfo-libpack3113
```

## 7. 用 CMake 生成 VS 工程

打开 PowerShell，执行：

```powershell
$cmake = 'C:\CMake\bin\cmake.exe'
$src = 'D:\project\LightWork3D\FreeCAD'
$build = 'E:\fc\build-relwithdebinfo-libpack3113'
$libpack = 'E:\fc\LibPack-1.1.0-v3.1.1.3-Release'

$env:Path = @(
  'C:\CMake\bin',
  'D:\VisualStudio\MSBuild\Current\Bin',
  'D:\VisualStudio\Common7\IDE',
  'C:\Git\cmd',
  'C:\Windows\System32',
  'C:\Windows',
  'C:\Windows\System32\Wbem',
  'C:\Windows\System32\WindowsPowerShell\v1.0',
  "$libpack\bin",
  "$libpack\lib"
) -join ';'

& $cmake `
  -S $src `
  -B $build `
  -G 'Visual Studio 17 2022' `
  -A x64 `
  -D FREECAD_LIBPACK_USE=ON `
  -D FREECAD_LIBPACK_DIR=$libpack `
  -D CMAKE_CONFIGURATION_TYPES=RelWithDebInfo
```

成功后会生成：

```text
E:\fc\build-relwithdebinfo-libpack3113\FreeCAD.sln
```

## 8. 编译前先记住一个坑

这套环境里，`TechDraw` 模块会触发 MSVC 的编译器堆空间不足：

```text
error C1060: 编译器的堆空间不足
```

这不是源码坏了。  
解决办法是不改源码，只在编译时强制：

```text
/MP1
```

也就是让 `cl.exe` 单进程编译重模块。

## 9. 编译整个工程

继续在 PowerShell 里执行：

```powershell
$cmake = 'C:\CMake\bin\cmake.exe'
$build = 'E:\fc\build-relwithdebinfo-libpack3113'
$libpack = 'E:\fc\LibPack-1.1.0-v3.1.1.3-Release'

$env:Path = @(
  'C:\CMake\bin',
  'D:\VisualStudio\MSBuild\Current\Bin',
  'D:\VisualStudio\Common7\IDE',
  'C:\Git\cmd',
  'C:\Windows\System32',
  'C:\Windows',
  'C:\Windows\System32\Wbem',
  'C:\Windows\System32\WindowsPowerShell\v1.0',
  "$libpack\bin",
  "$libpack\lib"
) -join ';'

$env:_CL_ = '/MP1'

& $cmake --build $build --config RelWithDebInfo --target ALL_BUILD --parallel 1
```

说明：

- `--parallel 1` 是 MSBuild 外层单并发
- `_CL_=/MP1` 是 C/C++ 编译器内层单并发

这两个都保留，最稳。

## 10. 不要直接运行 build 目录里的 FreeCAD.exe

很多人编译成功后，第一反应是去点：

```text
E:\fc\build-relwithdebinfo-libpack3113\bin\RelWithDebInfo\FreeCAD.exe
```

这通常会报各种缺 DLL，比如：

- `xerces-c_3_2.dll`
- `icuuc74.dll`
- `boost_program_options-vc143-mt-x64-1_87.dll`
- `pyside6.abi3.dll`
- `shiboken6.abi3.dll`

原因不是没编好，而是它只是构建产物，不是整理好的运行目录。

## 11. 生成真正可运行的安装目录

编译完成后执行：

```powershell
$cmake = 'C:\CMake\bin\cmake.exe'
$build = 'E:\fc\build-relwithdebinfo-libpack3113'
$prefix = 'E:\fc\run-FreeCAD-1.1.1'

& $cmake --install $build --config RelWithDebInfo --prefix $prefix
```

执行完以后，真正建议运行的是：

```text
E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe
```

## 12. 推荐运行方式

推荐做法不是双击某个 `bat`，而是：

1. 先执行 `INSTALL`
2. 然后在 Visual Studio 里直接按 `F5`

这样有几个好处：

- 断点能直接生效
- 环境变量配置固定在 VS 里，不容易忘
- 每次改完代码后可以继续用同一套调试入口

运行时真正使用的程序是：

```text
E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe
```

## 13. 在 VS 中打开哪个目录

你在 Visual Studio 里要打开的是：

```text
E:\fc\build-relwithdebinfo-libpack3113
```

准确地说，是打开这个文件：

[E:\fc\build-relwithdebinfo-libpack3113\FreeCAD.sln](E:\fc\build-relwithdebinfo-libpack3113\FreeCAD.sln)

不要打开：

- `D:\project\LightWork3D\FreeCAD` 作为“编译入口”
- `E:\fc\run-FreeCAD-1.1.1` 作为“解决方案目录”

这两个都不是 VS 编译入口。

## 14. 在 VS 中怎样直接 F5 运行

### 14.1 启动工程

打开解决方案后：

1. 配置切到 `RelWithDebInfo | x64`
2. 右键 `FreeCADMain`
3. 选择“设为启动项目”

### 14.2 调试配置

打开：

`FreeCADMain -> 属性 -> 配置属性 -> 调试`

填写：

`命令`

```text
E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe
```

`工作目录`

```text
E:\fc\run-FreeCAD-1.1.1\bin
```

`环境`

```text
FREECAD_LIBPACK_BIN=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin
PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin;E:\fc\LibPack-1.1.0-v3.1.1.3-Release\lib;E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin\Lib\site-packages\PySide6;E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin\Lib\site-packages\shiboken6;E:\fc\run-FreeCAD-1.1.1\bin;%PATH%
QT_PLUGIN_PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\plugins
QML2_IMPORT_PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\qml
```

配完以后，直接按 `F5`。

注意：

- `FREECAD_LIBPACK_BIN` 这一行不要漏
- 它不是可有可无的变量
- 在 Windows + Python 3.12 下，很多模块会靠它触发 `os.add_dll_directory(...)`
- 如果漏掉它，程序本体可能能启动，但打开带 `Part`、`Measure`、`TechDraw`、`PartDesignGui` 的工程时会报 `DLL load failed while importing ...`

### 14.3 如果打开自带工程时报模块导入失败

如果你打开 FreeCAD 自带工程后，消息面板里出现类似这些错误：

```text
DLL load failed while importing Part
DLL load failed while importing Measure
DLL load failed while importing TechDraw
DLL load failed while importing PartDesignGui
Cannot create object 'Page'
Cannot create object 'Template'
Cannot create object 'Hatch'
```

先不要怀疑源码，也不要先改代码。

先检查下面 4 件事：

1. 你运行的是不是 `E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe`
2. 你是不是已经执行过 `INSTALL`
3. VS 调试环境里有没有 `FREECAD_LIBPACK_BIN=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin`
4. `PATH` 里有没有 LibPack 的 `bin/lib`、PySide6、shiboken6、运行目录的 `bin`

这类报错在当前这套环境下，绝大多数都属于“VS 调试环境没配完整”，不是源码本身坏了。

## 15. 每次改完代码后该怎么做

推荐顺序：

1. 在 VS 里编译你改动的项目
2. 再编一次 `ALL_BUILD`
3. 再执行一次 `INSTALL`
4. 在 VS 里按 `F5`

如果你不执行 `INSTALL`，运行目录里的文件可能不是最新的。

## 16. 常见错误和对应处理

### 错误 1：`python312_d.lib` 找不到

原因：

- 你在编 `Debug`
- 但 LibPack 是 release 版

解决：

- 不要用 `Debug`
- 用 `RelWithDebInfo` 或 `Release`

### 错误 2：`boost::program_options ... contains` 链接失败

原因：

- LibPack 版本不匹配

解决：

- 改用 `LibPack-1.1.0-v3.1.1.3-Release`

### 错误 3：`No space left on device` / `磁盘空间不足`

原因：

- 盘满了

解决：

- 清理旧 build
- 清理旧 LibPack
- 清理 Temp
- 把构建目录移到 `E:`

### 错误 4：`C1060 编译器的堆空间不足`

原因：

- `TechDraw` 太重
- 编译器内部并发太高

解决：

```powershell
$env:_CL_='/MP1'
cmake --build E:\fc\build-relwithdebinfo-libpack3113 --config RelWithDebInfo --target ALL_BUILD --parallel 1
```

### 错误 5：直接双击 exe 提示缺 DLL

原因：

- 你点的是构建产物目录里的裸 `exe`

解决：

- 不要直接点 `build\bin\RelWithDebInfo\FreeCAD.exe`
- 先执行 `INSTALL`
- 然后在 VS 中把启动命令设为 `E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe`
- 并在 VS 调试配置里补好 `PATH`、`QT_PLUGIN_PATH`、`QML2_IMPORT_PATH`

### 错误 6：打开自带工程时报 `DLL load failed while importing Part/Measure/TechDraw/PartDesignGui`

原因：

- 运行时不是源码坏了
- 而是 VS 的调试环境缺少关键变量
- 最常见的是漏掉 `FREECAD_LIBPACK_BIN`

解决：

- 确认已经执行过 `INSTALL`
- 在 VS 的调试环境中加入：

```text
FREECAD_LIBPACK_BIN=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin
```

- 同时保留：

```text
PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin;E:\fc\LibPack-1.1.0-v3.1.1.3-Release\lib;E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin\Lib\site-packages\PySide6;E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin\Lib\site-packages\shiboken6;E:\fc\run-FreeCAD-1.1.1\bin;%PATH%
QT_PLUGIN_PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\plugins
QML2_IMPORT_PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\qml
```

说明：

- 这类问题通常可以通过环境配置解决
- 不需要先修改任何源码

## 17. 一套最终可复用的命令

### 生成工程

```powershell
$cmake = 'C:\CMake\bin\cmake.exe'
$src = 'D:\project\LightWork3D\FreeCAD'
$build = 'E:\fc\build-relwithdebinfo-libpack3113'
$libpack = 'E:\fc\LibPack-1.1.0-v3.1.1.3-Release'

$env:Path = @(
  'C:\CMake\bin',
  'D:\VisualStudio\MSBuild\Current\Bin',
  'D:\VisualStudio\Common7\IDE',
  'C:\Git\cmd',
  'C:\Windows\System32',
  'C:\Windows',
  'C:\Windows\System32\Wbem',
  'C:\Windows\System32\WindowsPowerShell\v1.0',
  "$libpack\bin",
  "$libpack\lib"
) -join ';'

& $cmake -S $src -B $build -G 'Visual Studio 17 2022' -A x64 -D FREECAD_LIBPACK_USE=ON -D FREECAD_LIBPACK_DIR=$libpack -D CMAKE_CONFIGURATION_TYPES=RelWithDebInfo
```

### 编译

```powershell
$env:_CL_='/MP1'
cmake --build E:\fc\build-relwithdebinfo-libpack3113 --config RelWithDebInfo --target ALL_BUILD --parallel 1
```

### 安装到运行目录

```powershell
cmake --install E:\fc\build-relwithdebinfo-libpack3113 --config RelWithDebInfo --prefix E:\fc\run-FreeCAD-1.1.1
```

### 运行

打开：

[E:\fc\build-relwithdebinfo-libpack3113\FreeCAD.sln](E:\fc\build-relwithdebinfo-libpack3113\FreeCAD.sln)

确认：

- 启动项目是 `FreeCADMain`
- 配置是 `RelWithDebInfo | x64`
- 已执行过 `INSTALL`
- 调试命令指向 `E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe`

然后按：

```text
F5
```

---

如果你严格按这份文档走，基于当前这份源码和这套 LibPack，已经实测可以成功编译并运行。  
如果后面换了源码分支，第一件事先确认：**LibPack 版本是不是还匹配。**