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

# FreeCAD Windows 编译运行傻瓜指南

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


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

- 源码分支：`releases/FreeCAD-1-1`
- 源码版本：`1.1.1-28-g94f4cb77f6`
- 构建入口：`PowerShell + cmake`
- 构建配置：`RelWithDebInfo | x64`
- LibPack：`LibPack-1.1.0-v3.1.1.3-Release`

## 第一部分：提前准备

### 1. 先理解三个目录

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

建议按下面这样放：

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

也就是：

- 源码和 `build` 放在一块
- LibPack 依赖放在另一块
- 最后生成的可运行 app 再放到另一块

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

### 2. 需要安装的软件

至少准备好这些：

1. `CMake`
2. `Git`
3. PowerShell
4. 当前 PowerShell 环境里已经能通过 `cmake` 调起可用的 Windows C++ 编译环境

建议：

- 用 64 位系统
- `C:` 盘和 `D:` 盘都预留足够空间
- `D:` 盘最好预留 100GB 以上
- 不要编 `Debug`，本文统一使用 `RelWithDebInfo`
- 预留20g以上的可用运行内存

先检查命令是否可用：

```powershell
cmake --version
git --version
```

如果 `cmake` 生成时报找不到 C++ 编译器，说明当前 PowerShell 环境还不能编 C++，先切到你平时能编译 FreeCAD 的 PowerShell 环境。

### 3. 下载源码

```powershell
git clone https://git.ngsk.tech/ngskcloud/LightWork3D.git D:\LightWork3D
```

确认源码在以下目录：

```text
D:\LightWork3D\
```

切换到 `dev` 分支：

```powershell
cd D:\LightWork3D
git checkout dev
```

### 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
D:\LibPack-1.1.0-v3.1.1.3-Release
```
依赖版本最好版本跟本文的版本一样。

### 5. 清理磁盘空间

确保 `C:` 盘和 `D:` 盘空间足够。

建议开始前检查：

- 是否存在旧的 `D:\LightWork3D\build`
- 是否存在旧的运行目录 `D:\FreeCAD-1.1.1`
- Windows 临时目录是否过大
- LibPack 是否解压完整

如果之前构建失败过，建议先换一个新的 `build` 目录，或者清空旧的 `D:\LightWork3D\build` 后再生成。

## 第二部分：构建生成

### 6. 新建构建目录

先准备几个路径变量，后面的命令都复用它们：

```powershell
$src = 'D:\LightWork3D'
$build = 'D:\LightWork3D\build'
$libpack = 'D:\LibPack-1.1.0-v3.1.1.3-Release'
$run = 'D:\FreeCAD-1.1.1'
```

新建构建目录：

```powershell
New-Item -ItemType Directory -Force $build
```

### 7. 用 CMake 生成工程

继续在 PowerShell 里执行：

```powershell
cmake `
  -S $src `
  -B $build `
  -D FREECAD_LIBPACK_USE=ON `
  -D FREECAD_LIBPACK_DIR=$libpack `
  -D CMAKE_CONFIGURATION_TYPES=RelWithDebInfo `
  -D CMAKE_INSTALL_PREFIX=$run `
  -D CMAKE_DISABLE_FIND_PACKAGE_Shiboken6=TRUE `
  -D CMAKE_DISABLE_FIND_PACKAGE_PySide6=TRUE
```

生成完成后，构建文件会在：

```text
D:\LightWork3D\build
```

### 8. 编译整个工程

继续在 PowerShell 里执行：

```powershell
cmake --build $build --config RelWithDebInfo --parallel 20
```

说明：

- `--parallel 20` 是20个并发任务，理论可以支持电脑上最大线程数。若编译出错，请降低并发任务数量。


### 9. 安装工程

编译完成后执行：

```powershell
cmake --install $build --config RelWithDebInfo --prefix $run --parallel 20
```

执行完以后，运行：

```text
D:\FreeCAD-1.1.1\bin\FreeCAD.exe
```

## 第三部分：常见问题

### 错误 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
- 清理旧运行目录

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

原因：

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

解决：

```powershell
$env:_CL_='/MP1'
cmake --build $build --config RelWithDebInfo --parallel 1
```

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

原因：

- 你点的是构建产物目录里的裸 `exe`
- 不是安装后的运行目录

解决：

- 不要直接点 `D:\LightWork3D\build\bin\RelWithDebInfo\FreeCAD.exe`
- 先执行 `cmake --install $build --config RelWithDebInfo --prefix $run`
- 然后运行 `D:\run-FreeCAD-1.1.1\bin\FreeCAD.exe`
- 启动前补好 `FREECAD_LIBPACK_BIN`、`PATH`、`QT_PLUGIN_PATH`、`QML2_IMPORT_PATH`

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

原因：

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

解决：

- 确认已经执行过安装：

```powershell
cmake --install $build --config RelWithDebInfo --prefix $run
```

- 在启动 FreeCAD 前加入：

```powershell
$env:FREECAD_LIBPACK_BIN = "$libpack\bin"
$env:PATH = "$libpack\bin;$libpack\lib;$libpack\bin\Lib\site-packages\PySide6;$libpack\bin\Lib\site-packages\shiboken6;$run\bin;$env:PATH"
$env:QT_PLUGIN_PATH = "$libpack\plugins"
$env:QML2_IMPORT_PATH = "$libpack\qml"
```

说明：

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

### 错误 7：改完代码后运行结果没变

原因：

- 你只编译了 build 目录
- 没有重新安装到运行目录

解决：

```powershell
cmake --build $build --config RelWithDebInfo --parallel 1
cmake --install $build --config RelWithDebInfo --prefix $run
```

然后再运行：

```powershell
& "$run\bin\FreeCAD.exe"
```

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