Gentoo 升級後 libpng 1.5 導致編譯失敗：gda、opencv、wxPython 修復實戰

Gentoo 系統升級將 libpng 從 1.4 升級至 1.5 後，大量套件因 API 變更（結構體隱藏、動態庫版本號變更）導致編譯失敗。本文記錄三種典型失敗場景的修復方案，供遇到相似 SONAME 升級問題時參考。

背景：libpng 1.5 破壞性變更

• 動態庫版本：libpng14.so → libpng15.so（SONAME 變更）；
• 公共結構體（png_struct, png_info）隱藏，僅保留不透明指標與存取函式；
• 不再隱含依賴 zlib，需顯式 #include 。

案例一：gnome-extra/libgda 鏈接失敗找不到 -lpng14

現象： 鏈接階段報錯 -lpng14 not found，但源碼 Makefile 中無硬編碼。

根因： /usr/lib64/*.la (libtool 封存) 殘留舊版依賴資訊，內含 -lpng14。

修復步驟：

1. 搜尋殘留引用：grep -r "png14" /usr/lib64/*.la
2. 重新編譯相關套件：emerge --ask @preserved-rebuild 或逐個 emerge -1 套件名
3. 若重建後 .la 仍未更新，手動修改 .la 檔案將 -lpng14 改為 -lpng15
4. 重新 emerge libgda 完成。

案例二：opencv 編譯錯誤 'MAX_MEM_LEVEL' undeclared

現象： 編譯 modules/highgui/src/grfmt_png.cpp 失敗，缺少 zlib 定義。

根因： libpng 1.5 不再透過 png.h 間接引入 zlib，需顯式包含。

修復：編寫補丁強制包含 zlib.h

--- modules/highgui/src/grfmt_png.cpp.old
+++ modules/highgui/src/grfmt_png.cpp
@@ -55,6 +55,7 @@
 #include 
 #else
 #include 
+#include 
 #endif
 #include "grfmt_png.hpp"

將補丁放入 /etc/portage/patches/media-libs/opencv/，建立本地 ebuild 覆蓋並重新 emerge opencv。

案例三：wxPython 結構體存取失敗（無補丁可用）

現象： 代碼直接通過結構體指標存取成員（如 png_ptr->width），libpng 1.5 隱藏結構體導致大量編譯錯誤。

狀態： 官方遲遲未釋出相容補丁，需等待上游修復或降級 libpng（emerge =libpng-1.4* 並 package.mask）。

通用排查與修復流程

1. emerge @preserved-rebuild 重建所有保留庫；
2. revdep-rebuild --library libpng14.so 專門重建依賴舊庫的套件；
3. 檢查 /usr/lib64/*.la 殘留引用，手動修正或 lafilefixer --justfixit；
4. 對於隱藏結構體導致的編譯錯誤，需為各套件編寫適配補丁（包含 zlib.h、改用存取函式）；
5. 實在無解時，暫時 package.mask 新版 libpng，待上游修復。

教訓總結

• 重大庫 SONAME 升級前，必先 emerge -p @preserved-rebuild 評估影響範圍；
• 保留 .la 檔案是 Gentoo 特有痛點，定期 lafilefixer 清理；
• 上游遷移至不透明結構體是大勢所趨，下游適配需預留時間窗口。

Gentoo 使用者面對庫升級導致的連鎖編譯失敗，核心對策是「重建保留庫 → 清理 .la 殘留 → 逐個適配補丁」。