簡介PoDoFo 0.9.4 的 Visual Studio 2010 工程專為需要在 Visual Studio 2010 環(huán)境下編譯使用 PoDoFo C 類庫的開發(fā)者準(zhǔn)備。官方推薦的 CMake 生成解決方案流程常常失敗該資源已手工搭建好核心代碼工程直接生成動(dòng)態(tài)庫與靜態(tài)庫。壓縮包共三百七十個(gè)文件以二百六十三個(gè)頭文件和九十三個(gè) C 源文件為主體另含 freetype2 與 zlib 的預(yù)編譯靜態(tài)庫和 VS 項(xiàng)目文件整體體積僅二點(diǎn)四三兆字節(jié)未包含 Samples 等示例代碼。已在 Windows 10 六十四位系統(tǒng)、Visual Studio 2010 下驗(yàn)證編譯通過核心源碼覆蓋 PDF 文檔讀取、頁面解析、字體嵌入、圖像處理、加密解密等常用模塊。資源內(nèi)頭文件與庫目錄集中放置便于自行調(diào)整鏈接路徑源碼保留原始注釋適合有一定 C 基礎(chǔ)的開發(fā)者閱讀和改造。無論快速集成 PDF 能力還是深入研究 PoDoFo 內(nèi)部實(shí)現(xiàn)這套工程都能減少環(huán)境配置與依賴折騰可直接作為二次開發(fā)基礎(chǔ)。已有七百四十八人學(xué)習(xí)下載。 在 Windows 下編譯開源 C 庫是個(gè)長期存在的折磨尤其是當(dāng)你手里只有一臺(tái)裝著 VS2010 的老機(jī)器或者一個(gè)只支持 VS2010 的遺留工程時(shí)。我這次折騰的是 podofo 0.9.4一個(gè)老牌的 PDF 處理庫前后花了兩天時(shí)間中間栽了無數(shù)跟頭最后總算把完整的 VS2010 工程跑通庫也編出來了。這篇文章就把完整過程記錄下來包括 CMake 怎么配、依賴庫怎么處理、編完怎么集成到自己工程里以及我踩過的那些文檔里根本不會(huì)寫的坑。先說清楚 podofo 是什么免得有人誤入。它是一個(gè)開源的 PDF 庫支持讀取、修改、寫入 PDF 文件也能提取文本、解析表單、處理加密文檔。0.9.4 是 2013 年前后的版本雖然不算新但 API 相對穩(wěn)定很多老項(xiàng)目用的就是這一版。這次需要的場景是給一個(gè)歷史遺留的 MFC 程序增加 PDF 生成功能編譯環(huán)境鎖定 VS2010所以我才專門把 podofo 0.9.4 的 VS2010 工程完整搭出來。如果你也在做類似的事或者說你就想讓一個(gè)老庫在舊工具鏈下老老實(shí)實(shí)工作這篇文章應(yīng)該能幫你省掉不少試錯(cuò)時(shí)間。1. 先搞清楚 podofo 0.9.4 的編譯難點(diǎn)在哪里1.1 這個(gè)庫自身的問題podofo 0.9.4 這套代碼本身不復(fù)雜但它有個(gè)老派開源項(xiàng)目常見的毛病編譯依賴特別多。官方源碼包里有CMakeLists.txt理論上可以生成任意 Visual Studio 版本對應(yīng)的工程但前提是你得把依賴庫全部準(zhǔn)備齊全尤其是libpngPNG 圖像編解碼libjpegJPEG 圖像編解碼zlib壓縮解壓幾乎繞不開freetype字體渲染OpenSSL處理 PDF 加密和簽名可選但編譯時(shí)默認(rèn)會(huì)找libtiffTIFF 圖像支持可選但默認(rèn)也會(huì)找這就引出第一個(gè)問題podofo 的 CMake 腳本并不會(huì)幫你自動(dòng)下載這些依賴項(xiàng)。你必須先把它們各自編譯好再在 CMake 里指定路徑。而這些依賴庫本身也有版本兼容問題跟 VS2010 搭配起來就是地獄難度。1.2 為什么偏偏要在 VS2010 上弄有人可能會(huì)問為什么不升級(jí)到新版的 Visual Studio省得這么折騰原因很現(xiàn)實(shí)有些項(xiàng)目因?yàn)橛昧死系牡谌娇丶?、老的?qū)動(dòng) SDK、或者客戶的環(huán)境鎖定只能鎖定 VS2010 編譯。再加上 VS2010 對 C 標(biāo)準(zhǔn)的支持停留在遠(yuǎn)古水平拿新版庫代碼硬編會(huì)碰到大量語法錯(cuò)誤與其改庫代碼不如就把 podofo 0.9.4 這個(gè)同時(shí)代的版本編出來。VS2010 還有一個(gè)操作上的細(xì)節(jié)它用的編譯器是 MSVC 16.0對應(yīng) VC10運(yùn)行時(shí)是 v100。之后版本的庫如果用了新的 C11 特性在 VS2010 上基本都會(huì)翻車。所以找?guī)彀姹緯r(shí)要認(rèn)準(zhǔn) 0.9.4 這種和 VS2010 同年代的版本別拿最新的 0.9.8 去試純屬浪費(fèi)時(shí)間。1.3 編譯產(chǎn)物與使用場景最終編好的 podofo 會(huì)生成兩個(gè)關(guān)鍵產(chǎn)物一個(gè)是靜態(tài)庫或 DLL取決于你 CMake 怎么配另一個(gè)是一堆頭文件。對于 VS2010 工程而言最省心的用法是把 podofo 編成靜態(tài)庫然后在你自己的程序里把頭文件路徑和庫文件路徑加進(jìn)工程配置。靜態(tài)庫的好處是發(fā)布時(shí)不用帶一堆 DLL對老系統(tǒng)部署非常友好。當(dāng)然如果你有多種程序都要用 podofo那編成 DLL 可以減少編譯時(shí)間。我個(gè)人更推薦靜態(tài)庫原因是 podofo 的依賴庫本身就多如果每個(gè)依賴都弄成 DLL發(fā)布時(shí)拷 DLL 都能把你逼瘋。2. 構(gòu)建前的準(zhǔn)備工具鏈、依賴與目錄規(guī)劃2.1 工具鏈準(zhǔn)備VS2010 SP1 必須裝第一個(gè)容易忽略的大坑是VS2010 必須要打 SP1否則 CMake 生成工程或者編譯過程中會(huì)出現(xiàn)各種莫名奇妙的錯(cuò)誤。尤其是如果你在 Win10 或 Win11 上裝 VS2010不打 SP1 的話連安裝可能都別別扭扭。SP1 的離線安裝包以前微軟官方有下載現(xiàn)在不在官方渠道了但網(wǎng)上能找到。裝好之后建議順手驗(yàn)證一下編譯器版本在命令行里執(zhí)行cl如果能顯示出 Microsoft (R) 32-bit C/C Optimizing Compiler Version 16.00.30319.01就說明環(huán)境正常。如果你看到的是 16.00.xxxxx 以下的老版本多半是沒打 SP1。另外注意CMake 版本不要用太新的。CMake 4.x 已經(jīng)明確放棄 VS2010 支持CMake 3.20 以上對 VS2010 的生成器支持也有退化跡象我實(shí)測最穩(wěn)的是 CMake 3.18.x。別看 CMake 只是個(gè)生成工具版本不對生成的 .sln 文件打開后會(huì)有各種兼容提示工程屬性頁里有些選項(xiàng)還會(huì)錯(cuò)亂。2.2 準(zhǔn)備第三方依賴庫這是整個(gè)過程中最耗時(shí)的一步。podofo 0.9.4 的 CMake 腳本會(huì)查找 zlib、libpng、libjpeg、freetype、OpenSSL、libtiff。你不可能指望它自己找到所以最好手動(dòng)編譯或者直接找編譯好的 Windows 版本庫。我當(dāng)時(shí)的做法是zlib直接拿 zlib 1.2.11 源碼包里的 VS2010 工程打開contrib/vstudio/vc10/zlibvc.sln分別編譯 Win32 的 Debug 和 Release 版本。libpng需要先有 zlib。下載 libpng 1.6.37里面自帶 CMakeLists 和 vstudio 工程用 CMake 生成 VS2010 工程后再編譯。注意 libpng 的 CMake 配置里要手動(dòng)指定 ZLIB_ROOT。libjpeg用 jpeg-9b 版本里面的結(jié)構(gòu)很簡單直接拿它的 VS2010 工程文件編就行。如果找不到工程文件也可以手動(dòng)創(chuàng)建一個(gè)空工程把源碼加進(jìn)去編譯成靜態(tài)庫。freetype老版本 freetype 2.5.5 自帶builds/windows/vc2010工程目錄直接打開編譯即可。新版 freetype 目錄結(jié)構(gòu)變化很大沒必要用新版。OpenSSL這個(gè)最惡心。OpenSSL 1.0.2 系列支持 VC2010但編譯需要 Perl還需要 NASM。如果不需要加密 PDF可以在 CMake 配置時(shí)直接關(guān)掉PODOFO_HAVE_OPENSSL別跟它死磕。libtiff不是必要項(xiàng)如果不用 TIFF 圖片處理同樣建議關(guān)掉。這里有一個(gè)關(guān)鍵技巧所有依賴庫最好統(tǒng)一編譯成靜態(tài)庫而且運(yùn)行庫設(shè)置要和 podofo 工程保持一致。如果你在用/MT或/MTd靜態(tài)運(yùn)行庫那 podofo 和所有依賴庫也都得用/MT或/MTd混著用一定鏈接報(bào)錯(cuò)。我因?yàn)橥祽衵lib 編的是/MD后來 link 時(shí)一堆libcmt.lib和msvcrt.lib沖突整整折騰半天。2.3 目錄規(guī)劃與命名約定建議建一個(gè)規(guī)范的第三方庫目錄方便 CMake 查找。我的目錄結(jié)構(gòu)是這樣的D:\thirdparty ├── zlib │ ├── include │ └── lib ├── libpng │ ├── include │ └── lib ├── libjpeg │ ├── include │ └── lib └── freetype ├── include └── lib每個(gè)庫的 lib 目錄里統(tǒng)一把文件命名為libpng.lib、libjpeg.lib、zlib.lib、freetype.libDebug 版本可以加個(gè)_d后綴別讓 CMake 傻傻分不清。這個(gè)步驟看著簡單實(shí)際很關(guān)鍵CMake 默認(rèn)找?guī)鞎r(shí)是按固定名字找的你文件名起得亂七八糟后面全是在跟 CMake 報(bào)錯(cuò)斗智斗勇。3. 用 CMake 生成 VS2010 工程的核心步驟3.1 第一次配置 CMake 的參數(shù)podofo 源碼解壓后進(jìn)入根目錄用 Cmake GUI 或者命令行配置。先說說最省心的 Cmake GUI 操作路徑打開 CMake GUI源碼目錄選 podofo 0.9.4 根目錄構(gòu)建目錄單獨(dú)建一個(gè)build-vc10文件夾別跟源碼混在一起否則后面想刪掉重新生成很麻煩點(diǎn)擊 Configure生成器選Visual Studio 10 2010如果選了 Win64就選Visual Studio 10 2010 Win64這取決于你要編 32 位還是 64 位。一般老項(xiàng)目都是 32 位選前者就行首次配置必然報(bào)錯(cuò)最重要的是看紅色報(bào)錯(cuò)項(xiàng)逐個(gè)解決3.2 解決 CMake 找不到依賴庫的報(bào)錯(cuò)第一次 Configure 后CMake 會(huì)列出一堆未找到的變量常見的有ZLIB_INCLUDE_DIR、ZLIB_LIBRARYPNG_PNG_INCLUDE_DIR、PNG_LIBRARYJPEG_INCLUDE_DIR、JPEG_LIBRARYFREETYPE_INCLUDE_DIR_FT2BUILD、FREETYPE_LIBRARYOPENSSL_INCLUDE_DIR、OPENSSL_LIBRARIESTIFF_INCLUDE_DIR、TIFF_LIBRARY這些變量必須手動(dòng)指定路徑。比如設(shè)置ZLIB_INCLUDE_DIR為D:/thirdparty/zlib/includeZLIB_LIBRARY為D:/thirdparty/zlib/lib/zlib.lib。遇到OPENSSL和TIFF找不到時(shí)如果不需要這些功能直接去 CMake 的變量列表里找到對應(yīng)的PODOFO_HAVE_OPENSSL和PODOFO_HAVE_TIFF之類的選項(xiàng)把勾去掉或者設(shè)為空。有些細(xì)分變量叫PODOFO_USE_STATIC_OPENSSL不用管只要主開關(guān)關(guān)了就行。如果你第一次 Configure 后界面是白板說明 CMake 緩存還沒生成點(diǎn) Configure 后它會(huì)變成紅色錯(cuò)誤項(xiàng)正常。根據(jù)我的經(jīng)驗(yàn)至少要把所有紅色項(xiàng)清零、列表底部沒有明顯錯(cuò)誤信息點(diǎn) Generate 才能生成 VS2010 工程文件。3.3 編譯過程需要多長時(shí)間的預(yù)期點(diǎn) Generate 之后會(huì)在構(gòu)建目錄里生成podofo.sln。用 VS2010 打開它在解決方案資源管理器里找到podofo項(xiàng)目直接右鍵生成。首次編譯時(shí)間取決于你機(jī)器性能一般吃 5 到 15 分鐘不等。如果你之前依賴庫編譯時(shí)踩了坑這里會(huì)爆出一堆 LNK 錯(cuò)誤先不要慌逐個(gè)看是哪個(gè)依賴沒找對。我在這一步遇到的典型問題是 freetype 的頭文件路徑找不到。因?yàn)?freetype 頭文件有兩種組織方式一種有ft2build.h在外層一種沒有。CMake 查FREETYPE_INCLUDE_DIR_FT2BUILD時(shí)要用包含ft2build.h的那個(gè)目錄而不是 freetype 的根目錄。這個(gè)坑文檔里寫得不清不楚我把兩個(gè)變量都指到同一層結(jié)果編譯時(shí)爆了二十多個(gè)ft2build.h: No such file or directory才意識(shí)到問題。3.4 確認(rèn)編譯產(chǎn)物是否正常編譯成功后到build-vc10/src/Debug或Release目錄下查看會(huì)有podofo.lib或podofo.dll。如果你編的是靜態(tài)庫大概率只有.lib文件也可能附帶一些.exp和.pdb。這時(shí)候可以把一個(gè)簡單的 PDF 文件丟給 podofo 自帶的測試工具試一下看看能否正常讀取。當(dāng)然podofo 的很多工具函數(shù)本身編譯出來也不一定會(huì)暴露出來最穩(wěn)妥的驗(yàn)證方式是自己寫個(gè)幾行代碼調(diào)用。但在這個(gè)階段只要看到podofo.lib生成成功基本上就說明庫本身沒問題可以進(jìn)入集成階段了。4. 編譯一個(gè)最小測試程序驗(yàn)證庫能不能用4.1 配置包含目錄、庫目錄與附加依賴項(xiàng)這一步很容易翻車。VS2010 的工程屬性配置里要依次設(shè)置C/C - 常規(guī) - 附加包含目錄把 podofo 的源碼根目錄加進(jìn)去。因?yàn)?podofo 的頭文件經(jīng)常是#include podofo/podofo.h所以源碼根目錄必須要在包含路徑里鏈接器 - 常規(guī) - 附加庫目錄把編譯好的podofo.lib所在目錄加進(jìn)去鏈接器 - 輸入 - 附加依賴項(xiàng)手動(dòng)敲入podofo.lib或者用生成后的 lib 文件名同時(shí)還要把 zlib、libpng、libjpeg、freetype 這些依賴庫的.lib一并加進(jìn)附加依賴項(xiàng)。比如podofo.lib zlib.lib libpng.lib libjpeg.lib freetype.lib如果你鏈接時(shí)提示某個(gè)函數(shù)找不到先檢查是不是漏了哪個(gè)依賴庫。再提示一次所有庫的/MT/MD設(shè)置要一致否則鏈接時(shí)就會(huì)有LNK2038這類運(yùn)行庫不匹配的錯(cuò)誤而且是在工程里看不出來的那種隱藏問題。4.2 寫一個(gè)最基礎(chǔ)的程序來驗(yàn)證鏈接為了驗(yàn)證庫能不能用我寫了一個(gè)非常簡單的程序創(chuàng)建一個(gè)空白 PDF往里面加一頁文本。核心代碼就這幾行#include podofo/podofo.h #include iostream using namespace PoDoFo; int main() { PdfStreamedDocument document(test.pdf); PdfPage* pPage document.CreatePage(PdfPage::CreateStandardPageSize(PdfPageSizeType::PdfPageSize_A4)); PdfPainter painter; painter.SetPage(pPage); painter.DrawText(100, 100, Hello PoDoFo on VS2010); painter.FinishDrawing(); document.Close(); std::cout PDF created successfully! std::endl; return 0; }注意PdfPageSizeType::PdfPageSize_A4這個(gè)枚舉在 0.9.4 里是有的但不同版本的 podofo 可能 API 有變化。如果你用的是 0.9.4這段代碼基本可以編譯通過。編譯后運(yùn)行如果生成了test.pdf那就是真的成功了。4.3 為什么不建議用 Debug 版本跑生產(chǎn)我測試時(shí)習(xí)慣先用 Debug 配置跑通但實(shí)際發(fā)布時(shí)會(huì)切成 Release。podofo 0.9.4 的 Debug 版本在 VS2010 下跟 Release 版本行為差異很大主要是因?yàn)檎{(diào)試迭代器和 STL 檢查在某些 PDF 操作中會(huì)影響性能。所以最后集成到正式工程里務(wù)必用 Release 版本的 podofo 庫并且在工程配置里保持運(yùn)行庫一致否則運(yùn)行時(shí)會(huì)崩得莫名其妙。另外如果你要發(fā)布程序給別人使用還要注意 podofo 是否依賴其他 DLL。如果是靜態(tài)庫就不存在這個(gè)問題但如果你編的是 DLL必須把 podofo.dll 和依賴庫的 DLL 一起拷貝到可執(zhí)行文件目錄。最保險(xiǎn)的方法是用 Dependencies 或者 Process Explorer 打開生成的 exe 看一眼加載了哪些 DLL別等別人報(bào)錯(cuò)找不到 dll才追悔莫及。5. 常見問題與排查技巧實(shí)錄5.1 LNK2038運(yùn)行庫不匹配這個(gè)問題我在前面反復(fù)提過因?yàn)檎娴奶Ｒ娏?。典型?bào)錯(cuò)是LNK2038: mismatch detected for RuntimeLibrary: value MT_StaticRelease doesnt match value MD_DynamicRelease一般原因就是 podofo 工程里設(shè)置的是多線程靜態(tài)庫/MT但你自己的工程用的是動(dòng)態(tài)庫/MD。解決辦法是進(jìn)入項(xiàng)目屬性把運(yùn)行庫設(shè)置成一致。如果你依賴庫也多那所有庫都得統(tǒng)一。最簡單的做法是全部用/MT、/MTd這樣發(fā)布時(shí)不用帶 VC 運(yùn)行庫在舊系統(tǒng)上部署也方便。5.2 頭文件路徑找不到podofo/podofo.h這個(gè)基本都是包含目錄沒設(shè)置對。podofo 的頭文件組織方式是源碼根目錄下有個(gè)src目錄里面podofo.h被藏在多層路徑下。最穩(wěn)妥的方法是把 podofo 源碼的src目錄和根目錄都加到附加包含目錄里然后代碼里統(tǒng)一用#include podofo/podofo.h如果你直接寫#include podofo.h編譯時(shí)會(huì)找不到因?yàn)轭^文件并不在工程文件的同目錄下。5.3 編譯時(shí)爆大量 C4996 或 C4244 警告VS2010 對 C4996使用了不安全的 C 函數(shù)非常敏感podofo 0.9.4 又是 2013 年的代碼里面用了一堆strcpy、sprintf這類函數(shù)。編譯時(shí)會(huì)產(chǎn)生大量警告不影響功能但看著糟心?？梢栽诠こ虒傩岳锇丫婕?jí)別調(diào)低或者直接禁用 C4996C/C - 高級(jí) - 禁用特定警告填入 4996如果想保持代碼整潔也可以定義_CRT_SECURE_NO_WARNINGS宏。這個(gè)方法對任何老庫都有效。5.4 Unicode 字符集 vs 多字節(jié)字符集VS2010 工程創(chuàng)建時(shí)默認(rèn)字符集是多字節(jié)但很多老代碼寫的是char*podofo 內(nèi)部處理文件名也是面向窄字符的。如果你的工程設(shè)置成了 Unicode 字符集調(diào)用 podofo 的打開文件 API 時(shí)可能碰到類型不匹配的編譯錯(cuò)誤比如PdfStreamedDocument構(gòu)造函數(shù)要求const char*而你傳的是CString那就得手動(dòng)轉(zhuǎn)換CString strPath _T(test.pdf); CT2A asciiPath(strPath); PdfStreamedDocument doc(asciiPath);這個(gè)坑在 MFC 程序里很常見如果你新寫的是純控制臺(tái)程序就不用操心。5.5 編譯 podofo 時(shí)報(bào)錯(cuò)找不到pthread.h有些版本的 podofo 在 Windows 下會(huì)去找 pthread 頭文件但 0.9.4 默認(rèn)是不依賴 pthread 的。如果遇到這種錯(cuò)誤八成是 CMake 誤開了什么選項(xiàng)或者在 FindThreads 那里把 pthread 選中了。去 CMake 配置里把跟 thread 相關(guān)的選項(xiàng)都關(guān)掉再重新生成工程。如果還不行檢查你的依賴庫里是否有某個(gè)庫比如 freetype 的某些版本內(nèi)部依賴 pthread。Windows 下沒有 pthread.h碰上了可以直接刪掉工程里的 pthread 引用或者使用 Windows 自帶的CreateThread替代但這一步比較麻煩。5.6 重新生成工程時(shí) CMakeCache 殘留改 CMake 配置改到煩躁的時(shí)候我建議直接把整個(gè)build-vc10目錄刪掉重建不要嘗試在舊緩存上反復(fù)橫跳。CMakeCache.txt 里的殘留變量會(huì)讓新配置受到干擾特別是路徑變了之后它還會(huì)固執(zhí)地尋找舊路徑。簡單粗暴刪除構(gòu)建目錄重新 Configure 和 Generate常常能解決很多奇怪問題。6. 一些個(gè)人沉淀下來的編譯經(jīng)驗(yàn)這次折騰 podofo 0.9.4 和 VS2010 讓我重新認(rèn)識(shí)到一個(gè)問題老庫在舊工具鏈下編譯并不是沒有章法關(guān)鍵是依賴關(guān)系的梳理。很多人一上來就想先把 podofo 直接編出來結(jié)果發(fā)現(xiàn)缺這個(gè)缺那個(gè)一下子就被勸退了。如果先花時(shí)間把依賴庫全部準(zhǔn)備好、統(tǒng)一運(yùn)行庫模式、規(guī)劃好目錄后面 CMake 配置就是單純指路徑的事情。另外想特別提一點(diǎn)編譯開源庫時(shí)不要迷信官網(wǎng)給的 README。很多時(shí)候那些文檔對應(yīng)的是 Linux 環(huán)境在 Windows 上跑完全不是一回事。我建議直接把 CMake 當(dāng)成主心骨只要把 CMake 的變量逐個(gè)搞清楚編譯路徑就基本掌控在自己手里。VS2010 老歸老它畢竟是微軟官方的編譯器對老版本庫的兼容性反而比新版 Visual Studio 好得多你根本不用擔(dān)心像 VS2019 那樣因?yàn)闃?biāo)準(zhǔn)支持過度而編譯不過。最后再分享一個(gè)小技巧如果你編譯的不是庫而是最終程序一定要在工程屬性里把鏈接器 - 生成調(diào)試信息打開并且把/INCREMENTAL選項(xiàng)正確設(shè)置。VS2010 的鏈接器很脆Debug 編譯失敗后有時(shí)會(huì)留下一個(gè)壞的 .ilk 文件導(dǎo)致反復(fù)報(bào)錯(cuò)刪掉Debug目錄里的.ilk文件再重新生成就能恢復(fù)。這個(gè)小坑我第一次遇到時(shí)排查了大半天希望你能繞過去。本文還有配套的精品資源點(diǎn)擊獲取