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