Pulse 文件管理器源码构建教程:CMake+Ninja 从零编译完整指南,含 Windows 8.1 兼容版与安装包打包
Pulse 文件管理器源码构建教程:CMake+Ninja 从零编译完整指南,含 Windows 8.1 兼容版与安装包打包
Pulse 是一款为 Windows 打造的现代文件管理器,支持多标签、全盘索引、拼音搜索与空格快速预览。本文带你用 CMake + Ninja 从零编译 Pulse 源码(当前版本 1.0.53),并分别产出面向 Windows 10/11 和 Windows 8.1 的安装包,适合想在本地构建、二次开发或学习其构建体系的开发者。
一、环境准备:Pulse 源码编译依赖清单
Pulse 使用 C++20 + Win32 + Direct2D 技术栈,仅支持 Windows x64 + MSVC 工具链(CMakeLists.txt 中会强制检查,非 MSVC 会直接报错退出)。
| 依赖 | 版本要求 | 用途 |
|---|---|---|
| Visual Studio C++ 工具链(MSVC) | VS 2022 及以上,勾选「C++ 桌面开发」 | 编译全部二进制 |
| CMake | 3.25+ | 构建配置(CMakeLists.txt 声明最低版本) |
| Ninja | 最新版 | 构建生成器,编译速度优于默认生成器 |
| PowerShell | 7.2+ | 发布打包脚本(仅打包安装程序时需要) |
| Python | 3.x | 安装程序打包器(仅打包时需要) |
获取源码(仓库为只读镜像,克隆到本地目录后操作):
git clone https://gitcode.com/gh_mirrors/pulse52/pulse
cd pulse
版本号定义在 version.txt 中,当前为 1.0.53。CMake 会读取它生成 project(Pulse VERSION ...),并最终体现在安装包文件名里。
二、认识构建产物:Pulse 的多进程架构
编译完成后,构建目录中会生成一组协同工作的可执行文件(定义均位于 CMakeLists.txt):
| 产物 | 角色 |
|---|---|
pulse.exe |
主 UI 进程(src/app/、src/ui/ 源码,CMakeLists.txt#L433-L502) |
Pulse.Index.exe |
全盘索引与查询宿主,可注册为会话助手或系统服务(CMakeLists.txt#L504-L531) |
Pulse.Preview.exe |
缩略图解码与 Shell 预览宿主,独立进程隔离解析崩溃(CMakeLists.txt#L620-L651) |
Pulse.Document.exe |
文档解析宿主(PDF/Office 等) |
pulse_shell.exe |
Shell COM 隔离进程(回收站、资源管理器动词) |
pulse_elevated.exe |
受授权文件操作(提权删除等) |
pulse_integration.exe |
Shell 集成的注册/修复入口 |
lumatext.dll / pdfium.dll |
文本渲染与 PDF 渲染的第三方运行库 |
这种拆分让文件预览、索引写入等重任务不阻塞界面。主界面效果如下图所示,编译完成后就能体验:
三、快速开始:三步一键编译 Pulse(CMake + Ninja)
仓库根目录提供了封装脚本,首次编译只需三步:
第 1 步:克隆源码(见上文)。
第 2 步:运行一键构建脚本
.\build_release.bat
build_release.bat 内部依次做了三件事:
- 调用 scripts/vcvars.bat:通过 vswhere 自动定位已安装的 Visual Studio,并进入 x64 开发者环境;
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release配置构建(自动带上静态运行库、LumaText 等选项);cmake --build build开始编译。
第 3 步:运行编译产物
.\build\pulse.exe
如果你更喜欢手动掌控每一步,等价的 CMake 命令是:
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
💡 文本渲染说明:构建时若找到仓库内置的 LumaText 包则启用
LumaText::D2D,找不到时自动回退到 DirectWrite(CMakeLists.txt#L61-L74),两种情况都能正常出包,不影响首次编译。
启动后选中任意文件按空格,即可验证快速预览链路是否工作正常:
四、读懂关键构建选项:CMakeLists.txt 要点
了解几个核心 CMake 选项,之后无论手动构建还是改 CI 都不会迷路:
| 选项 | 默认 | 说明 |
|---|---|---|
PULSE_WIN81_CANDIDATE |
OFF | 开启后要求 Windows 8.1 兼容工具链,并切换更新清单(CMakeLists.txt#L18-L22) |
CMAKE_MSVC_RUNTIME_LIBRARY |
MultiThreaded |
默认静态链接 VC 运行库,产物免装运行库(CMakeLists.txt#L9-L12) |
PULSE_WITH_LUMATEXT |
ON | 是否启用 LumaText 文本渲染 |
LUMATEXT_SOURCE_DIR |
空 | 指定 LumaText 源码树用于开发构建 |
PULSE_WITH_SELFTEST |
OFF | 在 pulse.exe 内嵌 --selftest 回归套件(仅测试用) |
PULSE_UPDATE_MANIFEST_URL |
官方地址 | 更新检查地址;置空可禁用自动更新 |
静态运行库(/MT)意味着安装包不需要附带 vcruntime140.dll 等 DLL,部署更干净,详见 docs/static-runtime-packaging.md。
五、构建 Windows 8.1 兼容版
Pulse 官方提供 Windows 10/11 与 Windows 8.1 两个 64 位版本,功能一致(见 docs/windows-compatibility.md)。构建 8.1 版的关键约束是:必须使用 VS 2022 的 v143 工具集,因为更新的 VS 版本已移除 Windows 8.1 运行库目标(build_win81.bat 开头注释说明了这一点)。
第 1 步:准备 v143 工具集(二选一)
- 本机已安装 VS 2022 的 x64 C++ 工具:直接设环境变量指向它:
$env:PULSE_VC_ROOT = "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.44.35207"
- 只有新版 VS:运行 tools/prepare_win81_toolchain.py,它会从微软官方清单下载并校验 SHA-256,把最小 v143 工具集解压到
tools\win81-toolchain(默认PULSE_VC_ROOT就指向这里),无需系统级安装。
第 2 步:一键构建
.\build_win81.bat /release
build_win81.bat 会以 PULSE_WIN81_CANDIDATE=ON + 静态运行库配置 CMake,并用 v143 的 cl.exe 编译到 build-win81 目录。
第 3 步:导入检查
python tools\audit_win81_imports.py build-win81
tools/audit_win81_imports.py 会扫描 PE 导入表,拒绝仅存在于 Windows 10+ 的启动期依赖。注意:静态导入检查不能替代真实系统上的运行验证。
六、打包安装程序:生成 PulseSetup.exe
编译产物还需要打成自解压安装程序。仓库已把整条流水线脚本化:
Windows 10/11 版:
.\build_installer.bat
build_installer.bat 先调用 build_release.bat,再交给 scripts/pack_setup.bat,后者按顺序执行:
- scripts/check_release_payload.ps1:校验产物中没有混入自测试套件;
- scripts/stage_installer_runtime.ps1:用 dumpbin 逐个检查 9 个载荷文件(
pulse.exe、Pulse.Index.exe、Pulse.Preview.exe、lumatext.dll等)的导入表,确保静态运行库链接无误; cmake --build build --target pulse_setup编译 C++ 启动器(src/setup/);- 调用 tools/pack_installer/pack_installer.py 把载荷打成
xz压缩流 + 自解压结构,输出dist\PulseSetup-1.0.53.exe。
Windows 8.1 版:
.\build_win81_installer.bat
build_win81_installer.bat 在打包前额外执行 audit_win81_imports.py,产物为 dist\PulseSetup-1.0.53-win81.exe。
一条命令走完全流程(构建 + 回归测试 + 打包),与 CI 环境完全一致:
pwsh ./scripts/build_release_ci.ps1 -Channel windows
pwsh ./scripts/build_release_ci.ps1 -Channel win81 -BuildDir build-ci-win81
scripts/build_release_ci.ps1 会先编译约 30 个测试目标并逐条运行回归测试,通过后再做生产编译、载荷检查与打包,适合作为发版前的本地验证。正式发布流程见 scripts/RELEASE.md 与 docs/automatic-updates.md。
七、常见问题排查
| 现象 | 原因与解决 |
|---|---|
Pulse requires MSVC (Windows SDK / D2D / NT API) |
未安装或未进入 MSVC 环境。安装 VS「C++ 桌面开发」工作负载,或用 .\build_release.bat(自动定位工具链) |
Windows 8.1 candidate builds require VS 2022 v143 |
8.1 构建误用了过新的工具集,按第五节设置 PULSE_VC_ROOT |
控制台提示 Pulse text renderer: DirectWrite |
未找到 LumaText 包,属正常回退,不影响出包 |
打包时报 Missing build output |
指定 build 目录中缺少 Pulse.Index.exe 等 9 个必需产物,先完整执行一次构建 |
| 打包时报静态运行库检查失败 | 二进制被改成了动态 CRT(/MD)编译,确认未覆盖 CMAKE_MSVC_RUNTIME_LIBRARY |
小结
- 日常构建:
git clone→.\build_release.bat→.\build\pulse.exe,三步完成; - 8.1 兼容版:v143 工具集 +
.\build_win81.bat /release+ 导入检查; - 安装程序:
.\build_installer.bat一条命令产出PulseSetup-1.0.53.exe(8.1 版为build_win81_installer.bat)。
延伸阅读:docs/windows-compatibility.md(双系统版本说明)、docs/static-runtime-packaging.md(静态运行库打包)、docs/automatic-updates.md(发布与更新签名机制)。




