ngskcloud
/
LightWork3D
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
dev
csm
main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '646209ba15'
${ noResults }
LightWork3D/docs/FreeCAD Windows 编译运行指南.md

12 KiB
Raw Blame History Unescape Escape

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 时，最好把“源码目录”“构建目录”“运行目录”分开。

建议按下面这样放：

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 源码放到：

D:\project\LightWork3D\FreeCAD

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

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

应该看到：

releases/FreeCAD-1-1

4. 下载完全匹配的 LibPack

这一步非常重要。

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

LibPack-1.1.0-v3.1.1.3-Release.7z

下载后解压到：

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

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

5. 清理磁盘空间

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

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

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

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

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

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

6. 新建构建目录

在 E: 盘新建目录：

E:\fc\build-relwithdebinfo-libpack3113

7. 用 CMake 生成 VS 工程

打开 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

成功后会生成：

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

8. 编译前先记住一个坑

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

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

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

/MP1

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

9. 编译整个工程

继续在 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

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

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. 生成真正可运行的安装目录

编译完成后执行：

$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

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

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

12. 推荐运行方式

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

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

这样有几个好处：

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

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

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

13. 在 VS 中打开哪个目录

你在 Visual Studio 里要打开的是：

E:\fc\build-relwithdebinfo-libpack3113

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

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 -> 属性 -> 配置属性 -> 调试

填写：

命令

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

工作目录

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

环境

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 自带工程后，消息面板里出现类似这些错误：

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 太重
  • 编译器内部并发太高

解决：

$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 的调试环境中加入：
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

说明：

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

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

生成工程

$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

编译

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

安装到运行目录

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

运行

打开：

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

确认：

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

然后按：

F5

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