如何给SumatraPDF贡献代码？从构建、调试到提交PR的完整开发者指南

如何给SumatraPDF贡献代码从构建、调试到提交PR的完整开发者指南【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdfSumatraPDF 是一款免费的开源多格式文档阅读器支持 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/mupdfPDF 渲染引擎vendored 内嵌cmd/BunTypeScript自动化脚本构建、代码生成、格式化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.tsbun 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. 调试 SumatraPDFWinDbg 与 -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 前的自查清单 ✅#检查项1bun cmd/build.ts -dbg通过且只运行了受影响的针对性测试2bun cmd/format.ts已跑prettier 管cmd/、tests/clang-format 管 C3没有手改生成文件ext/a-*、src/Commands.h、vs2022/4commit message 符合七条规则issue 号写在主题行末尾5新功能/命令/参数已同步更新docs/md/对应文档按这份指南走完构建、测试、调试、规范化提交四个阶段你的第一个 SumatraPDF PR 就具备被合并的完整要素了——祝提交顺利【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考