简介面向 Linux 桌面用户与开发者的一份 CHM 阅读工具源码包用于解决 Linux 环境下无法直接打开微软编译的 HTML 帮助文档这一常见困扰。chmsee 对中文 CHM 文档支持良好可解析并显示目录、索引与正文还提供全文搜索、书签管理、右键导航菜单等实用功能界面简洁适合经常查阅技术手册、离线文档的学习者与运维人员。压缩包共 111 个文件约 355KB以 C 与 C 源文件、头文件、automake 构建脚本am、m4、ac、configure 配置脚本为主另含 glade 界面描述、po 与 pot 多语言翻译、desktop 与 mime 桌面集成文件、gif 与 png 图标资源及 readme、changelog 等说明文档构成一套可编译的完整工程。已有 468 人学习下载读者可据此了解 CHM 解析实现、Firefox 插件集成方式与依赖库配置思路并自行编译安装使用。1. 从一次打不开的离线手册说起chmsee 在 Linux 上到底装什么上周帮某实验室的同事恢复一台旧开发机桌面环境是轻量级的 Xfce系统里躺着一份几百兆的 CHM 格式离线手册双击之后弹出来的却是一个空窗口标题栏写着 chmsee正文一片白。这种场景在 Linux 桌面里太常见了CHM 是 Windows 时代留下的帮助文档格式Linux 原生并不认它得靠专门的阅读器来解包渲染。chmsee 就是这类工具里比较老牌的一个基于 GTK 和 xulrunner 那一套技术栈界面朴素胜在能直接索引 CHM 内部的目录树和全文搜索。装不好会怎样轻则白屏、乱码重则一启动就段错误退出连报错都看不到。这篇笔记面向的是手里有 CHM 资料、想在 Linux 桌面上把它正常翻开的开发者从版本选择一路写到装完怎么验证中间踩过的坑一并记下来。2. 装前把环境列清chmsee 的依赖与版本取舍chmsee 不是一个能靠一条apt install就万事大吉的软件它的麻烦在于年代久远依赖链里混着 GTK2、xulrunner 和一堆 C 运行时库。动手之前先把环境摸清楚比装到一半再回头补依赖省事得多。这一章先把「装什么版本、依赖哪些包、系统怎么选」讲透后面几章才好落地。2.1 先确认发行版和桌面栈chmsee 的活跃年代大致对应 GTK2 时代所以它对桌面环境是有偏好的。GNOME 2、Xfce、MATE 这类还保留 GTK2 运行时的环境最省心纯 GTK3/GTK4 的现代桌面比如某些精简版 GNOME虽然也能跑但需要额外把 GTK2 的兼容库补齐。先跑两条命令看清楚底子# 看发行版和版本号决定后面用 apt 还是 dnf cat /etc/os-release # 看当前桌面是否还带 GTK2 运行时 pkg-config --modversion gtk-2.0 2/dev/null || echo GTK2 开发库未安装第一条命令输出里的ID和VERSION_ID决定了包管理器是apt还是dnf也决定了软件源里还能不能找到 chmsee 的现成包。第二条命令如果直接打印出版本号常见是 2.24.x说明 GTK2 开发库在如果走到echo分支说明得先补libgtk2.0-dev这类包。我一般会先看这两条再决定路线避免在 GTK3-only 的系统上硬编译最后卡在一堆找不到的头文件上。2.2 依赖清单与版本对照chmsee 的核心依赖可以分成三类GTK2 图形库、CHM 解析库chmlib、以及它自带的 xulrunner 渲染引擎。不同发行版打包时对这几样的版本要求略有差异下面这张表是我在几类常见系统上整理出来的对照装之前照着核一遍依赖项作用常见包名Debian 系常见包名RHEL 系版本要求GTK2 开发库界面绘制libgtk2.0-devgtk2-devel2.24 及以上chmlib解析 CHM 容器libchm-devchmlib-devel0.40 左右xulrunner渲染 HTML 内容视发行版而定视发行版而定与 chmsee 版本匹配GCC/G编译build-essentialgcc-c支持 C98 即可pkg-config找库路径pkg-configpkgconfig任意这里要特别说一句 xulrunner。它是 chmsee 渲染正文的关键但很多新发行版已经把它从主源里移除了只留一个残缺的兼容包。常见做法是优先用发行版自带的 chmsee 二进制包如果源里还有它会自动把 xulrunner 的依赖关系带进来只有当源里彻底没有时才考虑自己编译而自己编译时 xulrunner 的版本必须和 chmsee 源码里写死的接口对得上差一个大版本就可能链接失败。2.3 两条安装路线怎么选路线一包管理器直接装。适合 Debian/Ubuntu 的老版本、以及还维护 chmsee 包的衍生发行版。优点是依赖自动解决缺点是版本可能偏旧。路线二源码编译。适合源里已经没有 chmsee、或者需要打补丁修复白屏问题的场景。优点是可控缺点是依赖要自己一个个补齐。我一般的判断标准是先apt-cache search chmsee或dnf search chmsee探一下有包就走路线一没有再看源码。下面两章分别把这两条路线写清楚读者按自己系统的情况挑一条走即可。3. 包管理器安装从探源到首次启动这一章走路线一把「探源、装包、补依赖、首次启动」串成一条能照着敲的流程。包管理器安装看起来简单但 chmsee 这种老软件在新系统上经常出现「包装上了、依赖却缺一块」的情况所以每一步后面都跟一句怎么确认。3.1 探源与安装命令先确认源里到底有没有这个包别急着敲 install# Debian/Ubuntu 系搜索包名确认是否存在 apt-cache search chmsee # RHEL/Fedora 系同样先搜 dnf search chmsee如果搜索有结果说明源里有现成的包直接装# Debian/Ubuntu 系安装-y 表示自动确认 sudo apt install -y chmsee # RHEL/Fedora 系安装 sudo dnf install -y chmseeapt-cache search只查不装用来判断路线install -y里的-y是跳过交互确认适合脚本化操作手动装时去掉也无妨。装完先别急着打开 CHM跑一下版本查询确认二进制真的落地了# 确认可执行文件位置和是否能正常加载动态库 which chmsee ldd $(which chmsee) | grep not foundldd那条是关键如果输出里有not found说明有动态库没被依赖关系带进来这时候别硬启动先把缺的库补上否则一启动就是段错误。这一步是我踩过坑之后养成的习惯能提前把「装上了但跑不起来」的问题拦在启动之前。3.2 缺依赖时的补齐顺序ldd报缺库时补齐是有顺序的先补 GTK2 运行时再补 chmlib最后处理 xulrunner。原因是前两个是硬依赖缺了直接起不来xulrunner 缺了往往表现为能启动但正文白屏属于「半残」状态。# 补 GTK2 运行时和 chmlib 运行时Debian 系 sudo apt install -y libgtk2.0-0 libchm1 # 补开发库如果后面要编译或打补丁 sudo apt install -y libgtk2.0-dev libchm-devlibgtk2.0-0是运行时库libgtk2.0-dev是开发头文件只跑不编译的话装前者就够。libchm1同理。补完之后再跑一次ldd确认not found消失。如果缺的是 xulrunner 相关的库先看发行版有没有xulrunner或libxul的兼容包有就装没有就记下来留到第 5 章的排查里处理。3.3 首次启动与基础配置装好依赖后第一次启动建议从终端里跑这样报错能直接看到# 从终端启动保留标准错误输出 chmsee /path/to/manual.chm把/path/to/manual.chm换成你实际的 CHM 文件路径。从终端启动的好处是如果程序崩溃终端里会打印出类似Segmentation fault或 GTK 的警告这些信息比图形界面里一个空窗口有用得多。首次启动后如果界面正常、目录树能展开说明基础环境通了如果白屏先别怀疑安装多半是 xulrunner 渲染层的问题翻到第 5 章对照排查。基础配置方面chmsee 的设置项不多主要在「视图」里调字体和编码。中文 CHM 常见乱码原因是文档内部编码和程序默认编码不一致在设置里把编码手动指定为 GBK 或 GB18030 往往能解决。这个配置不写进配置文件也行每次打开时在菜单里选一次即可属于「知道在哪调」比「提前配好」更实用的项。4. 源码编译configure 参数与编译排错源里没有 chmsee 的时候就得自己编译。这条路线的难点不在敲命令而在 configure 阶段的各种「找不到」以及编译时老代码对新编译器的兼容问题。这一章按「取源码、配参数、编译、装」的顺序走每一步都写清楚失败时看哪里。4.1 取源码与目录准备源码一般是一个 tar 包解压后进目录。这里不写具体下载地址按你手里拿到的包名操作即可# 解压源码包x 解包、z 处理 gzip、f 指定文件 tar -xzf chmsee-*.tar.gz # 进入解压出来的目录 cd chmsee-*/解压后先别急着 configure扫一眼目录里有没有README和INSTALL老项目的这两个文件里经常写着它期望的 xulrunner 版本和额外的编译开关比盲目试参数高效。我一般会先ls看一眼有没有configure脚本没有的话说明得先跑autogen.sh生成。4.2 configure 的关键参数configure 阶段最容易卡在「找不到某个库」。下面这组参数是我在多数环境下会用的起步配置# 指定安装前缀关闭不需要的调试符号显式给出 chmlib 路径 ./configure \ --prefix/usr/local \ --disable-debug \ --with-chmlib-prefix/usr--prefix/usr/local把安装目录定在/usr/local避免污染系统自带的/usr--disable-debug关掉调试符号减小体积、加快编译--with-chmlib-prefix/usr告诉 configure 去哪里找 chmlib 的头文件和库如果 chmlib 装在别处把路径改成实际位置。configure 跑完会打印一份摘要重点看xulrunner那一行是不是yes如果是no说明渲染引擎没找到后面编译出来的程序大概率白屏。如果 configure 报Package gtk-2.0 was not found说明 pkg-config 找不到 GTK2 的.pc文件常见做法是确认libgtk2.0-dev已装并用export PKG_CONFIG_PATH/usr/lib/pkgconfig把路径补进环境变量再重跑。4.3 编译与安装configure 通过后就可以编译了。老代码在新 GCC 上编译最常见的报错是头文件缺失和 C 标准不兼容# 并行编译-j 后面的数字按 CPU 核心数填这里用 4 make -j4 # 编译成功后安装到 configure 指定的前缀 sudo make installmake -j4里的-j是并行任务数填多了内存吃紧反而慢填少了浪费核心一般按nproc的结果来。如果编译中途报fatal error: xxx.h: No such file or directory先确认对应的-dev包装了没有如果报的是 C 语法相关的错误老代码用了一些新标准里被移除的写法常见做法是在CXXFLAGS里加-stdc98或-fpermissive让编译器宽容一些# 用兼容模式重新编译适合老代码遇到新编译器报语法错 make clean make CXXFLAGS-stdc98 -fpermissive -j4make clean先清掉上一次的中间产物避免新旧目标文件混在一起CXXFLAGS覆盖默认的 C 编译选项-stdc98让编译器按老标准解析-fpermissive把一些原本是错误的地方降级为警告。这两个参数是权宜之计能编过就行不必追求零警告。装完之后同样用ldd确认一遍动态库再按第 3.3 节的方式从终端启动验证。5. 避坑与排查chmsee 装完跑不起来的五种情况chmsee 的坑集中在「装完」和「跑起来」之间那一段界面出不来、正文白屏、中文乱码每一种背后原因都不一样。这一章按「现象 → 原因 → 解决」记五条我实际遇到过的照着对号入座能省不少时间。5.1 启动即段错误终端只打印 Segmentation fault现象命令行敲chmsee回车没有任何窗口终端直接输出Segmentation fault (core dumped)。原因绝大多数是动态库版本不匹配尤其是 xulrunner 的 ABI 和 chmsee 编译时链接的版本对不上程序在初始化渲染引擎时访问了非法地址。解决先用ldd $(which chmsee)看有没有not found有就补库没有的话用gdb chmsee跑一次看崩溃栈顶落在哪个库上。如果落在libxul相关符号说明 xulrunner 版本不对换一个和源码匹配的版本重装或者退回包管理器安装的二进制版本。5.2 窗口能开正文一片白现象程序正常启动左侧目录树也在点章节标题右侧正文区全白。原因渲染层没工作。chmsee 把 CHM 里的 HTML 抽出来交给 xulrunner 渲染xulrunner 缺失或初始化失败时界面框架还在内容区就是空的。解决确认 configure 摘要里 xulrunner 是yes如果是包管理器装的检查libxul兼容包是否装上。实在找不到匹配的 xulrunner可以退而求其次用 chmlib 自带的解包工具把 CHM 拆成 HTML 再用浏览器看虽然丢了目录联动但内容能读。5.3 中文显示成方块或乱码现象正文能显示但中文全是方块或者是一堆问号和乱码字符。原因编码不匹配。CHM 内部可能是 GBK/GB18030 编码程序按 UTF-8 去解自然对不上方块则是系统缺中文字体。解决先在 chmsee 的视图菜单里手动把编码切成 GB18030 试一次如果还是方块装一套中文字体如fonts-wqy-zenhei再用fc-cache -fv刷新字体缓存。这两步做完基本能正常显示。5.4 configure 报找不到 gtk-2.0现象源码编译时./configure中途退出提示Package gtk-2.0 was not found in the pkg-config search path。原因GTK2 开发库没装或者装了但.pc文件不在 pkg-config 的默认搜索路径里。解决先sudo apt install libgtk2.0-dev再pkg-config --modversion gtk-2.0确认能查到版本。查不到就手动指定路径export PKG_CONFIG_PATH/usr/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH然后重跑 configure。路径里的架构目录按实际系统调整。5.5 装完命令找不到现象make install显示成功但敲chmsee提示command not found。原因安装前缀是/usr/local而/usr/local/bin不在当前 shell 的PATH里或者没跑ldconfig导致动态库缓存没更新。解决先echo $PATH看有没有/usr/local/bin没有就export PATH/usr/local/bin:$PATH并写进 shell 配置文件再sudo ldconfig刷新动态库缓存。两步做完再试一次通常就正常了。6. 装完怎么验证三步确认 chmsee 真的能用装完不等于能用尤其 chmsee 这种依赖链长的老工具得有一套固定的验证动作。我一般分三步走先验二进制和动态库再验 CHM 解析最后验渲染和中文显示。三步都过才算这套环境真的落地。第一步验二进制和动态库。这一步在装完当下就做别等打开文件才发现问题# 确认可执行文件存在且所有动态库都能解析 which chmsee ldd $(which chmsee) | grep -c not found第二条命令的grep -c统计not found出现的次数输出0才算干净。只要不是 0就回到第 5.1 节按缺库处理别往下走。第二步验 CHM 解析。拿一个结构完整的 CHM 文件从终端启动并观察目录树# 从终端启动同时把标准错误重定向到文件方便事后看 chmsee /path/to/manual.chm 2 /tmp/chmsee_err.log启动后看左侧目录树能不能完整展开、点章节标题右侧有没有内容。如果目录树正常但正文白屏翻第 5.2 节如果连目录树都出不来看/tmp/chmsee_err.log里的报错多半是 CHM 文件本身损坏或 chmlib 版本太老解析不了。第三步验渲染和中文。打开一个含中文的章节确认字体不是方块、编码不是乱码。这一步没有命令可跑靠肉眼但可以配合字体检查# 确认系统里至少有一套中文字体可用 fc-list :langzh | head -n 3fc-list :langzh列出所有支持中文的字体head -n 3只看前三条有输出说明字体在。如果前面显示正常但这里查不到中文字体说明是程序内置了字体回退换个 CHM 文件可能就露馅建议还是把中文字体装上。三步验证下来我习惯把结果记一笔二进制路径、ldd是否干净、测试用的 CHM 文件名、中文是否正常。这套记录在换机器或重装系统时特别有用照着复现一遍就知道环境有没有退化。从那以后我每次装这类老工具都强制走一遍「ldd 干净、目录树能开、中文不乱」这三关少一关都不算装完。希望帮到你。本文还有配套的精品资源点击获取
