如何給SumatraPDF貢獻(xiàn)代碼從構(gòu)建、調(diào)試到提交PR的完整開發(fā)者指南【免費(fèi)下載鏈接】sumatrapdfSumatraPDF reader項(xiàng)目地址: https://gitcode.com/gh_mirrors/su/sumatrapdfSumatraPDF 是一款免費(fèi)的開源多格式文檔閱讀器支持 PDF、EPUB、MOBI、CBZ、FB2、CHM、XPS、DjVu采用 (A)GPLv3 許可證發(fā)布。本文是一份面向新手貢獻(xiàn)者的完整教程涵蓋代碼倉庫結(jié)構(gòu)、構(gòu)建系統(tǒng)、調(diào)試技巧與提交 Pull Request 的全流程規(guī)范。1. 先讀懂倉庫SumatraPDF 的代碼在哪里SumatraPDF 是一個面向 Windows 的 C 程序主要使用 Win32 API不使用 STL而是自帶字符串/容器/輔助函數(shù)位于src/base/。上手前先記住這幾個核心目錄目錄作用src/主程序 C 源碼UI、引擎、文檔模型等ext/第三方庫最重要的是ext/mupdfPDF 渲染引擎vendored 內(nèi)嵌cmd/BunTypeScript自動化腳本構(gòu)建、代碼生成、格式化tests/基于 Bun 的端到端 UI 測試腳本vs2022/生成的 Visual Studio 解決方案不要手動編輯docs/md/官方文檔源文件應(yīng)用內(nèi)手冊也來自這里官方貢獻(xiàn)入口文檔Contribute-to-SumatraPDF.md構(gòu)建系統(tǒng)細(xì)節(jié)見 Build-system.md。2. 環(huán)境準(zhǔn)備一鍵搭好 SumatraPDF 開發(fā)環(huán)境貢獻(xiàn) SumatraPDF 只需三樣?xùn)|西Visual Studio 2022免費(fèi)的 Community 版即可安裝時勾選「使用 C 的桌面開發(fā)」bun運(yùn)行時——項(xiàng)目的幾乎所有自動化任務(wù)都靠它完成構(gòu)建、代碼生成、跑測試、格式化git——獲取倉庫源碼git clone https://gitcode.com/gh_mirrors/su/sumatrapdf官方約定Visual Studio 命令行工具cl.exe、msbuild.exe等應(yīng)在 PATH 中可用構(gòu)建腳本會直接調(diào)用它們。3. 構(gòu)建 SumatraPDF一條命令出 exe構(gòu)建的唯一入口是cmd/build.ts見 build.tsbun cmd/build.ts -dbg # 調(diào)試版 bun cmd/build.ts -rel # 發(fā)布版 bun cmd/build.ts -asan # 64 位 AddressSanitizer 版構(gòu)建產(chǎn)物位于out/dbg64/SumatraPDF.exe靜態(tài)目標(biāo)為SumatraPDF-static.exe。幾個新手容易踩的坑不要手改vs2022/下的工程文件。它由 Premake 5 從 premake5.lua 和 premake5.files.lua 生成只有增刪源文件時才需要運(yùn)行bun cmd/premake.ts重新生成ext/a-*目錄是由 amalgam.ts 自動生成的「合訂」代碼嚴(yán)禁手改修改了src/下的.cpp/.c/.h后構(gòu)建前請先對改動文件跑 clang-format第三方ext/代碼除外。 技巧需要自定義編譯宏時往 src/BuildConfig.h 里加#define即可無需改動工程配置。4. 調(diào)試 SumatraPDFWinDbg 與 -for-testing 標(biāo)志4.1 日常調(diào)試Windbg 直接掛起官方推薦的調(diào)試方式agents.md 約定windbgx -Q -o -g ./out/dbg64/SumatraPDF.exe4.2 手動測試的黃金法則-for-testing啟動 SumatraPDF.exe 做臨時測試時務(wù)必傳-for-testing參數(shù)它會強(qiáng)制新實(shí)例啟動、不恢復(fù)上次會話、不保存設(shè)置——從而完全不干擾你正在使用的正式 SumatraPDF。4.3 崩潰與卡死排查用戶側(cè)的崩潰/卡死排查教程見 Debugging-Sumatra.md 與 Using-DrMemory.md。開發(fā)者調(diào)試崩潰時可結(jié)合cmd/下的輔助腳本analyze-crash.ts、crashes.ts。4.4 單元測試編譯進(jìn) exe 的內(nèi)置測試單元測試被編譯進(jìn)調(diào)試版的 SumatraPDF.exe推薦方式bun cmd/run-unit-tests.ts -dbg該腳本會構(gòu)建調(diào)試 exe、帶-unit-tests -for-ai運(yùn)行并自動捕獲斷言/崩潰調(diào)用棧輸出到out/config/unit-tests-*.txt無需等待調(diào)試器 UI。5. 寫好測試tests/ 目錄的命名約定SumatraPDF 的端到端測試是 Bun TypeScript 腳本驅(qū)動真實(shí)窗口做 UI 自動化FFI Win32 消息命名以 GitHub issue 號為準(zhǔn)測試腳本tests/issue-編號.ts如 issue-6101.ts附帶少量資源文件tests/issue-編號.ext資源較多時放入目錄tests/issue-編號-data/一個合格的測試必須導(dǎo)出testit()并在文件末尾接上runStandalone獨(dú)立運(yùn)行器新測試要注冊進(jìn) run-almost-all.ts太慢的加進(jìn) run-all.ts 的slowTests。驗(yàn)證修改時只跑受影響的單個測試如bun tests/issue-編號.ts不要動輒跑全量套件。6. 提交規(guī)范格式、commit message 與 PR 流程SumatraPDF 采用標(biāo)準(zhǔn) GitHub 模型fork 倉庫 → 提 Pull Request → 維護(hù)者審查合并。開始較大改動前建議先在 issue 區(qū)討論。6.1 代碼風(fēng)格硬性約定摘自 agents.md頭文件不放長篇注釋解釋性注釋寫在.cpp的定義處不用#pragma once字符串用自帶StrL(...)/fmt()體系而非std::string修復(fù) bug 時先寫測試、看它失敗、再寫修復(fù)改動ext/mupdf時必須在同一提交中把改動記錄為 ext/patches/ 下的.patch文件規(guī)則見 ext/patches/README.md否則下次升級 mupdf 會靜默丟失改動。6.2 Commit message 七條軍規(guī)主題行與正文之間空一行主題行 ≤ 50 字符72 為硬上限主題行首字母大寫主題行不以句號結(jié)尾使用祈使句Fix bug 而非 Fixed——檢驗(yàn)公式If applied, this commit will …正文手動折行于 72 字符正文解釋 what 和 why代碼自己解釋 how。修復(fù) GitHub issue 時把(fixes #編號)寫在主題行末尾例如fix crash on committing an empty zoom value (fixes #5909)6.3 生成代碼別手改新增高級設(shè)置、命令、命令行參數(shù)時改cmd/gen-*.ts后運(yùn)行bun cmd/gen-code.ts重新生成對應(yīng)的src/Settings.h、src/Commands.h、src/Flags.cpp并在 docs/md/Version-history.md 的下一版本區(qū)登記。7. 提交 PR 前的自查清單 ?#檢查項(xiàng)1bun cmd/build.ts -dbg通過且只運(yùn)行了受影響的針對性測試2bun cmd/format.ts已跑prettier 管cmd/、tests/clang-format 管 C3沒有手改生成文件ext/a-*、src/Commands.h、vs2022/4commit message 符合七條規(guī)則issue 號寫在主題行末尾5新功能/命令/參數(shù)已同步更新docs/md/對應(yīng)文檔按這份指南走完構(gòu)建、測試、調(diào)試、規(guī)范化提交四個階段你的第一個 SumatraPDF PR 就具備被合并的完整要素了——祝提交順利【免費(fèi)下載鏈接】sumatrapdfSumatraPDF reader項(xiàng)目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考