Pulse 文件管理器源码构建教程:CMake+Ninja 从零编译完整指南,含 Windows 8.1 兼容版与安装包打包

原创2026-10-24 18:21:531,747 阅读
文章标签:桌面应用人工智能AI 应用AI AgentMCP 服务全文检索语音

Pulse 文件管理器源码构建教程:CMake+Ninja 从零编译完整指南,含 Windows 8.1 兼容版与安装包打包

Pulse 是一款为 Windows 打造的现代文件管理器,支持多标签、全盘索引、拼音搜索与空格快速预览。本文带你用 CMake + Ninja 从零编译 Pulse 源码(当前版本 1.0.53),并分别产出面向 Windows 10/11 和 Windows 8.1 的安装包,适合想在本地构建、二次开发或学习其构建体系的开发者。

Pulse 文件管理器封面:现代化 Windows 文件浏览界面

一、环境准备: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 文件管理器深色主题主界面:多标签与侧栏浏览效果

Pulse 文件管理器多窗格分栏浏览:单栏、分屏与四宫格布局

三、快速开始:三步一键编译 Pulse(CMake + Ninja)

仓库根目录提供了封装脚本,首次编译只需三步:

第 1 步:克隆源码(见上文)。

第 2 步:运行一键构建脚本

.\build_release.bat

build_release.bat 内部依次做了三件事:

  1. 调用 scripts/vcvars.bat:通过 vswhere 自动定位已安装的 Visual Studio,并进入 x64 开发者环境;
  2. cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release 配置构建(自动带上静态运行库、LumaText 等选项);
  3. 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),两种情况都能正常出包,不影响首次编译。

启动后选中任意文件按空格,即可验证快速预览链路是否工作正常:

Pulse 文件管理器空格快速预览:Markdown 渲染与文件预览效果

四、读懂关键构建选项: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+ 的启动期依赖。注意:静态导入检查不能替代真实系统上的运行验证。

Pulse 文件管理器设置界面:外观、语言与系统集成选项

六、打包安装程序:生成 PulseSetup.exe

编译产物还需要打成自解压安装程序。仓库已把整条流水线脚本化:

Windows 10/11 版:

.\build_installer.bat

build_installer.bat 先调用 build_release.bat,再交给 scripts/pack_setup.bat,后者按顺序执行:

  1. scripts/check_release_payload.ps1:校验产物中没有混入自测试套件;
  2. scripts/stage_installer_runtime.ps1:用 dumpbin 逐个检查 9 个载荷文件(pulse.exe、Pulse.Index.exe、Pulse.Preview.exe、lumatext.dll 等)的导入表,确保静态运行库链接无误;
  3. cmake --build build --target pulse_setup 编译 C++ 启动器(src/setup/);
  4. 调用 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(发布与更新签名机制)。

登录后查看全文
pulse