如何给SumatraPDF贡献代码？从构建、调试到提交PR的完整开发者指南
【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf
SumatraPDF 是一款免费的开源多格式文档阅读器（支持 PDF、EPUB、MOBI、CBZ、FB2、CHM、XPS、DjVu），采用 (A)GPLv3 许可证发布。本文是一份面向新手贡献者的完整教程：涵盖代码仓库结构、构建系统、调试技巧与提交 Pull Request 的全流程规范。
1. 先读懂仓库：SumatraPDF 的代码在哪里
SumatraPDF 是一个面向 Windows 的 C++ 程序，主要使用 Win32 API，不使用 STL，而是自带字符串/容器/辅助函数（位于src/base/）。上手前，先记住这几个核心目录：
| 目录 | 作用 |
|---|---|
src/ | 主程序 C++ 源码（UI、引擎、文档模型等） |
ext/ | 第三方库，最重要的是ext/mupdf（PDF 渲染引擎，vendored 内嵌） |
cmd/ | Bun（TypeScript）自动化脚本：构建、代码生成、格式化 |
tests/ | 基于 Bun 的端到端 UI 测试脚本 |
vs2022/ | 生成的 Visual Studio 解决方案（不要手动编辑） |
docs/md/ | 官方文档源文件（应用内手册也来自这里） |
官方贡献入口文档：Contribute-to-SumatraPDF.md，构建系统细节见 Build-system.md。
2. 环境准备：一键搭好 SumatraPDF 开发环境
贡献 SumatraPDF 只需三样东西：
- Visual Studio 2022（免费的 Community 版即可），安装时勾选「使用 C++ 的桌面开发」；
- bun运行时——项目的几乎所有自动化任务都靠它完成（构建、代码生成、跑测试、格式化）；
- git——获取仓库源码：
git clone https://gitcode.com/gh_mirrors/su/sumatrapdf官方约定：Visual Studio 命令行工具（cl.exe、msbuild.exe等）应在 PATH 中可用，构建脚本会直接调用它们。
3. 构建 SumatraPDF：一条命令出 exe
构建的唯一入口是cmd/build.ts（见 build.ts）：
bun cmd/build.ts -dbg # 调试版 bun cmd/build.ts -rel # 发布版 bun cmd/build.ts -asan # 64 位 AddressSanitizer 版构建产物位于out/dbg64/SumatraPDF.exe（静态目标为SumatraPDF-static.exe）。
几个新手容易踩的坑：
- 不要手改
vs2022/下的工程文件。它由 Premake 5 从 premake5.lua 和 premake5.files.lua 生成；只有增删源文件时才需要运行bun cmd/premake.ts重新生成； ext/a-*目录是由 amalgam.ts 自动生成的「合订」代码，严禁手改；- 修改了
src/下的.cpp/.c/.h后，构建前请先对改动文件跑 clang-format（第三方ext/代码除外）。
💡 技巧：需要自定义编译宏时，往 src/BuildConfig.h 里加
#define即可，无需改动工程配置。
4. 调试 SumatraPDF：WinDbg 与 -for-testing 标志
4.1 日常调试：Windbg 直接挂起
官方推荐的调试方式（agents.md 约定）：
windbgx -Q -o -g ./out/dbg64/SumatraPDF.exe4.2 手动测试的黄金法则：-for-testing
启动 SumatraPDF.exe 做临时测试时，务必传-for-testing参数：它会强制新实例启动、不恢复上次会话、不保存设置——从而完全不干扰你正在使用的正式 SumatraPDF。
4.3 崩溃与卡死排查
用户侧的崩溃/卡死排查教程见 Debugging-Sumatra.md 与 Using-DrMemory.md。开发者调试崩溃时可结合cmd/下的辅助脚本：analyze-crash.ts、crashes.ts。
4.4 单元测试：编译进 exe 的内置测试
单元测试被编译进调试版的 SumatraPDF.exe，推荐方式：
bun cmd/run-unit-tests.ts -dbg该脚本会构建调试 exe、带-unit-tests -for-ai运行，并自动捕获断言/崩溃调用栈输出到out/<config>/unit-tests-*.txt，无需等待调试器 UI。
5. 写好测试：tests/ 目录的命名约定
SumatraPDF 的端到端测试是 Bun TypeScript 脚本，驱动真实窗口做 UI 自动化（FFI + Win32 消息），命名以 GitHub issue 号为准：
- 测试脚本：
tests/issue-<编号>.ts（如 issue-6101.ts） - 附带少量资源文件：
tests/issue-<编号>.<ext> - 资源较多时放入目录：
tests/issue-<编号>-data/
一个合格的测试必须：导出testit()并在文件末尾接上runStandalone独立运行器；新测试要注册进 run-almost-all.ts（太慢的加进 run-all.ts 的slowTests）。验证修改时只跑受影响的单个测试（如bun tests/issue-<编号>.ts），不要动辄跑全量套件。
6. 提交规范：格式、commit message 与 PR 流程
SumatraPDF 采用标准 GitHub 模型：fork 仓库 → 提 Pull Request → 维护者审查合并。开始较大改动前，建议先在 issue 区讨论。
6.1 代码风格硬性约定（摘自 agents.md）
- 头文件不放长篇注释：解释性注释写在
.cpp的定义处； - 不用
#pragma once； - 字符串用自带
StrL("...")/fmt()体系，而非std::string； - 修复 bug 时先写测试、看它失败、再写修复；
- 改动
ext/mupdf时，必须在同一提交中把改动记录为 ext/patches/ 下的.patch文件（规则见 ext/patches/README.md），否则下次升级 mupdf 会静默丢失改动。
6.2 Commit message 七条军规
- 主题行与正文之间空一行；
- 主题行 ≤ 50 字符（72 为硬上限）；
- 主题行首字母大写；
- 主题行不以句号结尾；
- 使用祈使句（"Fix bug" 而非 "Fixed"）——检验公式："If applied, this commit will …"；
- 正文手动折行于 72 字符；
- 正文解释 what 和 why，代码自己解释 how。
修复 GitHub issue 时，把(fixes #编号)写在主题行末尾，例如：
fix crash on committing an empty zoom value (fixes #5909)6.3 生成代码：别手改
新增高级设置、命令、命令行参数时，改cmd/gen-*.ts后运行bun cmd/gen-code.ts重新生成对应的src/Settings.h、src/Commands.h、src/Flags.cpp，并在 docs/md/Version-history.md 的下一版本区登记。
7. 提交 PR 前的自查清单 ✅
| # | 检查项 |
|---|---|
| 1 | bun cmd/build.ts -dbg通过，且只运行了受影响的针对性测试 |
| 2 | bun cmd/format.ts已跑（prettier 管cmd/、tests/，clang-format 管 C++） |
| 3 | 没有手改生成文件（ext/a-*、src/Commands.h、vs2022/） |
| 4 | commit message 符合七条规则，issue 号写在主题行末尾 |
| 5 | 新功能/命令/参数已同步更新docs/md/对应文档 |
按这份指南走完构建、测试、调试、规范化提交四个阶段，你的第一个 SumatraPDF PR 就具备被合并的完整要素了——祝提交顺利！
【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
