fix/修改图标和加载界面，修改编译文档-qdj-0522

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

@@ -2,60 +2,83 @@
 
 这份文档面向第一次在 Windows 上编译 FreeCAD 的同学。
 
-目标是：
-
-- 不改源码
-- 能在本机直接运行 FreeCAD
 
 本文档基于下面这套已经验证成功的组合：
 
 - 源码分支：`releases/FreeCAD-1-1`
 - 源码版本：`1.1.1-28-g94f4cb77f6`
-- 编译器：`cmake`
+- 构建入口：`PowerShell + cmake`
 - 构建配置：`RelWithDebInfo | x64`
 - LibPack：`LibPack-1.1.0-v3.1.1.3-Release`
 
-## 1. 先理解三个目录
+## 第一部分：提前准备
+
+### 1. 先理解三个目录
 
-编译 FreeCAD 时，最好把“源码目录”“构建目录”“运行目录”分开。
+编译 FreeCAD 时，最好把“源码和构建目录”“依赖目录”“运行目录”分开。
 
 建议按下面这样放：
 
 ```text
 D:\LightWork3D\                                  源码目录
-D:\LibPack-1.1.0-v3.1.1.3-Release                依赖目录
 D:\LightWork3D\build                             构建目录
-D:\run-FreeCAD-1.1.1                          安装后的运行目录
+D:\LibPack-1.1.0-v3.1.1.3-Release                依赖目录
+D:\FreeCAD-1.1.1                                 安装后的运行目录
 ```
 
+也就是：
+
+- 源码和 `build` 放在一块
+- LibPack 依赖放在另一块
+- 最后生成的可运行 app 再放到另一块
+
 不要把所有东西都堆在一个目录里。
 
-## 2. 需要安装的软件
+### 2. 需要安装的软件
 
 至少准备好这些：
 
-1. `Desktop development with C++` 工作负载
+1. `CMake`
-2. `CMake`
+2. `Git`
-3. `Git`
+3. PowerShell
+4. 当前 PowerShell 环境里已经能通过 `cmake` 调起可用的 Windows C++ 编译环境
 
 建议：
 
 - 用 64 位系统
+- `C:` 盘和 `D:` 盘都预留足够空间
 - `D:` 盘最好预留 100GB 以上
+- 不要编 `Debug`，本文统一使用 `RelWithDebInfo`
+
+先检查命令是否可用：
 
-## 3. 下载源码
+```powershell
+cmake --version
+git --version
+```
+
+如果 `cmake` 生成时报找不到 C++ 编译器，说明当前 PowerShell 环境还不能编 C++，先切到你平时能编译 FreeCAD 的 PowerShell 环境。
+
+### 3. 下载源码
+
+```powershell
+git clone https://git.ngsk.tech/ngskcloud/LightWork3D.git D:\LightWork3D
+```
 
-`git clone https://git.ngsk.tech/ngskcloud/LightWork3D.git`
+确认源码在以下目录：
 
-确认在以下目录：
 ```text
 D:\LightWork3D\
 ```
 
-切换到dev分支
+切换到 `dev` 分支：
 
+```powershell
+cd D:\LightWork3D
+git checkout dev
+```
 
-## 4. 下载完全匹配的 LibPack
+### 4. 下载完全匹配的 LibPack
 
 这一步非常重要。
 
@@ -68,216 +91,90 @@ D:\LightWork3D\
 ```text
 D:\LibPack-1.1.0-v3.1.1.3-Release
 ```
+依赖版本最好版本跟本文的版本一样。
 
-不要用 `3.1.1.2`。  
+### 5. 清理磁盘空间
-这份源码配 `3.1.1.2` 时，已经实测会在链接阶段报 `boost::program_options ... contains` 相关错误。
 
-## 5. 清理磁盘空间
+确保 `C:` 盘和 `D:` 盘空间足够。
-确保c盘d盘空间足够
-## 6. 新建构建目录
 
-在 `D:\LightWork3D\build ` 构建目录
+建议开始前检查：
 
-## 7. 用 CMake 生成工程
+- 是否存在旧的 `D:\LightWork3D\build`
-
+- 是否存在旧的运行目录 `D:\FreeCAD-1.1.1`
-```bash
+- Windows 临时目录是否过大
-cmake -S D:\LightWork3D -B D:\LightWork3D\bulid    
+- LibPack 是否解压完整
--DFREECAD_LIBPACK_DIR=D:\LibPack-1.1.0-v3.1.1.3-Release 
--DCMAKE_DISABLE_FIND_PACKAGE_Shiboken6=TRUE 
--DCMAKE_DISABLE_FIND_PACKAGE_PySide6=TRUE
-```
 
-## 8. 编译前先记住一个坑
+如果之前构建失败过，建议先换一个新的 `build` 目录，或者清空旧的 `D:\LightWork3D\build` 后再生成。
 
-这套环境里，`TechDraw` 模块会触发 MSVC 的编译器堆空间不足：
+## 第二部分：构建生成
-
-```text
-error C1060: 编译器的堆空间不足
-```
 
-这不是源码坏了。  
+### 6. 新建构建目录
-解决办法是不改源码，只在编译时强制：
 
-```text
+先准备几个路径变量，后面的命令都复用它们：
-/MP1
-```
-
-也就是让 `cl.exe` 单进程编译重模块。
-
-## 9. 编译整个工程
-
-继续在 PowerShell 里执行：
 
 ```powershell
-cmake --build D:\LightWork3D\bulid --config RelWithDebInfo --target INSTALL --parallel 4
+$src = 'D:\LightWork3D'
+$build = 'D:\LightWork3D\build'
+$libpack = 'D:\LibPack-1.1.0-v3.1.1.3-Release'
+$run = 'D:\FreeCAD-1.1.1'
 ```
 
-说明：
+新建构建目录：
-
-- `--parallel 1` 是 MSBuild 外层单并发
-- `_CL_=/MP1` 是 C/C++ 编译器内层单并发
-
-这两个都保留，最稳。
-
-## 10. 不要直接运行 build 目录里的 FreeCAD.exe
 
-很多人编译成功后，第一反应是去点：
+```powershell
-
+New-Item -ItemType Directory -Force $build
-```text
-D:\FreeCAD\bin\RelWithDebInfo\FreeCAD.exe
 ```
 
-这通常会报各种缺 DLL，比如：
+### 7. 用 CMake 生成工程
 
-- `xerces-c_3_2.dll`
+继续在 PowerShell 里执行：
-- `icuuc74.dll`
-- `boost_program_options-vc143-mt-x64-1_87.dll`
-- `pyside6.abi3.dll`
-- `shiboken6.abi3.dll`
-
-原因不是没编好，而是它只是构建产物，不是整理好的运行目录。
-
-## 11. 生成真正可运行的安装目录
-
-编译完成后执行：
 
 ```powershell
- cmake --build D:\LightWork3D\bulid --config RelWithDebInfo --target INSTALL 
+cmake `
-
+  -S $src `
- cmake --install D:\LightWork3D\bulid --config RelWithDebInfo --prefix D:\FreeCAD
+  -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:\FreeCAD\bin\RelWithDebInfo\FreeCAD.exe
+D:\LightWork3D\build
 ```
 
-# 到这一步一般就可以运行了。以下是常见问题：
+### 8. 编译整个工程
 
-## 12. 推荐运行方式
+继续在 PowerShell 里执行：
-
-推荐做法不是双击某个 `bat`，而是：
-
-1. 先执行 `INSTALL`
-2. 然后在 Visual Studio 里直接按 `F5`
-
-这样有几个好处：
-
-- 断点能直接生效
-- 环境变量配置固定在 VS 里，不容易忘
-- 每次改完代码后可以继续用同一套调试入口
-
-运行时真正使用的程序是：
-
-```text
-E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe
-```
-
-## 13. 在 VS 中打开哪个目录
-
-你在 Visual Studio 里要打开的是：
 
-```text
+```powershell
-E:\fc\build-relwithdebinfo-libpack3113
+cmake --build $build --config RelWithDebInfo --parallel 4
 ```
 
-准确地说，是打开这个文件：
+说明：
-
-[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 -> 属性 -> 配置属性 -> 调试`
 
-填写：
+- `--parallel 4` 是4个并发任务，理论可以支持电脑上最大线程数。若编译出错，请降低并发任务数量。
 
-`命令`
 
-```text
+### 9. 安装工程
-E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe
-```
 
-`工作目录`
+编译完成后执行：
-
-```text
-E:\fc\run-FreeCAD-1.1.1\bin
-```
-
-`环境`
 
-```text
+```powershell
-FREECAD_LIBPACK_BIN=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin
+cmake --install $build --config RelWithDebInfo --prefix $run
-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
+D:\FreeCAD-1.1.1\bin\FreeCAD.exe
-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` 找不到
 
@@ -312,7 +209,7 @@ Cannot create object 'Hatch'
 - 清理旧 build
 - 清理旧 LibPack
 - 清理 Temp
-- 把构建目录移到 `E:`
+- 清理旧运行目录
 
 ### 错误 4：`C1060 编译器的堆空间不足`
 
@@ -325,7 +222,7 @@ Cannot create object 'Hatch'
 
 ```powershell
 $env:_CL_='/MP1'
-cmake --build E:\fc\build-relwithdebinfo-libpack3113 --config RelWithDebInfo --target ALL_BUILD --parallel 1
+cmake --build $build --config RelWithDebInfo --parallel 1
 ```
 
 ### 错误 5：直接双击 exe 提示缺 DLL
@@ -333,37 +230,38 @@ cmake --build E:\fc\build-relwithdebinfo-libpack3113 --config RelWithDebInfo --t
 原因：
 
 - 你点的是构建产物目录里的裸 `exe`
+- 不是安装后的运行目录
 
 解决：
 
-- 不要直接点 `build\bin\RelWithDebInfo\FreeCAD.exe`
+- 不要直接点 `D:\LightWork3D\build\bin\RelWithDebInfo\FreeCAD.exe`
-- 先执行 `INSTALL`
+- 先执行 `cmake --install $build --config RelWithDebInfo --prefix $run`
-- 然后在 VS 中把启动命令设为 `E:\fc\run-FreeCAD-1.1.1\bin\FreeCAD.exe`
+- 然后运行 `D:\run-FreeCAD-1.1.1\bin\FreeCAD.exe`
-- 并在 VS 调试配置里补好 `PATH`、`QT_PLUGIN_PATH`、`QML2_IMPORT_PATH`
+- 启动前补好 `FREECAD_LIBPACK_BIN`、`PATH`、`QT_PLUGIN_PATH`、`QML2_IMPORT_PATH`
 
 ### 错误 6：打开自带工程时报 `DLL load failed while importing Part/Measure/TechDraw/PartDesignGui`
 
 原因：
 
 - 运行时不是源码坏了
-- 而是 VS 的调试环境缺少关键变量
+- 而是 PowerShell 运行环境缺少关键变量
 - 最常见的是漏掉 `FREECAD_LIBPACK_BIN`
 
 解决：
 
-- 确认已经执行过 `INSTALL`
+- 确认已经执行过安装：
-- 在 VS 的调试环境中加入：
 
-```text
+```powershell
-FREECAD_LIBPACK_BIN=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\bin
+cmake --install $build --config RelWithDebInfo --prefix $run
 ```
 
-- 同时保留：
+- 在启动 FreeCAD 前加入：
 
-```text
+```powershell
-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%
+$env:FREECAD_LIBPACK_BIN = "$libpack\bin"
-QT_PLUGIN_PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\plugins
+$env:PATH = "$libpack\bin;$libpack\lib;$libpack\bin\Lib\site-packages\PySide6;$libpack\bin\Lib\site-packages\shiboken6;$run\bin;$env:PATH"
-QML2_IMPORT_PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\qml
+$env:QT_PLUGIN_PATH = "$libpack\plugins"
+$env:QML2_IMPORT_PATH = "$libpack\qml"
 ```
 
 说明：
@@ -371,65 +269,25 @@ QML2_IMPORT_PATH=E:\fc\LibPack-1.1.0-v3.1.1.3-Release\qml
 - 这类问题通常可以通过环境配置解决
 - 不需要先修改任何源码
 
-## 17. 一套最终可复用的命令
+### 错误 7：改完代码后运行结果没变
 
-### 生成工程
+原因：
 
-```powershell
+- 你只编译了 build 目录
-$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 $build --config RelWithDebInfo --parallel 1
-cmake --build E:\fc\build-relwithdebinfo-libpack3113 --config RelWithDebInfo --target ALL_BUILD --parallel 1
+cmake --install $build --config RelWithDebInfo --prefix $run
 ```
 
-### 安装到运行目录
+然后再运行：
 
 ```powershell
-cmake --install E:\fc\build-relwithdebinfo-libpack3113 --config RelWithDebInfo --prefix E:\fc\run-FreeCAD-1.1.1
+& "$run\bin\FreeCAD.exe"
 ```
 
-### 运行
+如果严格按这份文档走，基于当前这份源码和这套 LibPack，已经实测可以成功编译并运行。
-
-打开：
-
-[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 版本是不是还匹配。**