企业官网建设流程全解析

• 构建工具
• 开发工具
• CLI

导读

FindHTMLHelp是 CMake 官方提供的一个find_package模块，用于在 Windows 平台上定位 Microsoft HTML Help Workshop 所附带的 HTML Help 编译器（hhc.exe）及其开发 API（htmlhelp.h头文件与htmlhelp.lib库），从而让项目能够以可复现的方式将 HTML 文档编译为.chm帮助文件，或链接使用 HTML Help API 的应用程序。读完本文，你将掌握该模块的全部结果变量与缓存变量语义、其底层搜索策略与源码实现细节，并能在自己的CMakeLists.txt中正确、安全地使用它。

一、模块概览：它解决什么问题

该模块的官方定位（见 Modules/FindHTMLHelp.cmake 文档块）是：

Finds the Microsoft HTML Help Compiler and its API which is part of the HTML Help Workshop.

即它负责查找两样东西：

1. HTML Help 编译器：hhc.exe，用于把 HTML 主题文件编译打包成.chm（Compiled HTML Help）格式的帮助文档；
2. HTML Help API 开发资源：htmlhelp.h头文件与htmlhelp.lib静态库，供那些需要在自己的应用程序内嵌帮助系统、调用HtmlHelp()等 API 的开发者链接使用。

模块的使用方式与 CMake 其他 Find 模块完全一致：

find_package(HTMLHelp [...])

其中[...]可以传入REQUIRED、QUIET、NO_MODULE等find_package通用选项。

二、重要前提：HTML Help Workshop 已进入维护模式（Deprecated）

模块文档块中有一处醒目提示，这是使用本模块前必须了解的背景：

HTML Help Workshop is in maintenance mode only and is considered deprecated. For modern documentation, consider alternatives such as Microsoft Help Viewer for producing.mshcfiles or web-based documentation tools.

即HTML Help Workshop 已停止功能迭代、仅处于维护模式，官方视为已弃用（deprecated）。因此，除非你的项目必须继续维护存量.chm帮助文件，否则文档建议考虑以下替代方案：

• Microsoft Help Viewer：用于生成.mshc（Microsoft Help Container）格式的新一代帮助文件；
• 基于 Web 的文档工具：例如各类在线文档站点方案，避免绑定已废弃的二进制帮助格式。

这一提示意味着：在新建项目中，应审慎评估是否仍要引入.chm依赖；而在维护老项目时，FindHTMLHelp依然是兼容历史构建系统的最稳妥选择。

三、结果变量：HTMLHelp_FOUND

模块定义了一个结果变量：

该变量在CMake 4.2 版本中新增（文档标注.. versionadded:: 4.2），符合 CMake 现代 Find 模块统一的Package_FOUND命名规范。下游代码通常这样使用：

find_package(HTMLHelp) if(HTMLHelp_FOUND) # 仅在找到时才继续配置相关目标 else() message(WARNING "HTML Help not found, skipping .chm generation") endif()

从实现上看（Modules/FindHTMLHelp.cmake），HTMLHelp_FOUND的判定逻辑非常简洁：只有编译器、头文件路径、库三者全部非空时才置TRUE，否则为FALSE：

if(HTML_HELP_COMPILER AND HTML_HELP_INCLUDE_PATH AND HTML_HELP_LIBRARY) set(HTMLHelp_FOUND TRUE) else() set(HTMLHelp_FOUND FALSE) endif()

这与文档中"结果变量"与"缓存变量"的划分完全对应：三个缓存变量是搜索的"产物"，HTMLHelp_FOUND是面向使用方的"结论"。

四、缓存变量详解：编译器、头文件与库

模块定义并填充三个缓存变量（Modules/FindHTMLHelp.cmake）：

三者用途明确：

• HTML_HELP_COMPILER：在构建阶段调用它把 HTML 源文件编译成.chm，例如通过add_custom_command或add_custom_target在构建时执行hhc.exe；
• HTML_HELP_INCLUDE_PATH：供集成 HTML Help API 的 C/C++ 目标添加头文件搜索路径，即target_include_directories(... ${HTML_HELP_INCLUDE_PATH})；
• HTML_HELP_LIBRARY：供链接使用 HTML Help API 的目标使用，即target_link_libraries(... ${HTML_HELP_LIBRARY})。

一个典型的链接场景：

find_package(HTMLHelp) if(HTMLHelp_FOUND) add_executable(MyApp main.cpp) target_include_directories(MyApp PRIVATE ${HTML_HELP_INCLUDE_PATH}) target_link_libraries(MyApp PRIVATE ${HTML_HELP_LIBRARY}) endif()

值得注意的是，这三个变量在搜索完成后都被mark_as_advanced标记为高级缓存变量（Modules/FindHTMLHelp.cmake），默认不会在 cmake-gui 的普通视图中展示，避免干扰用户界面。

五、源码级解析：模块的搜索策略

整个搜索过程被if(WIN32)条件包裹（Modules/FindHTMLHelp.cmake），意味着该模块只在 Windows 平台生效。在非 Windows 系统上调用它不会进行任何搜索，三个缓存变量保持为空，HTMLHelp_FOUND恒为FALSE。这与 HTML Help Workshop 仅面向 Windows 的产品定位一致。

5.1 编译器搜索：注册表驱动的路径探测

find_program(HTML_HELP_COMPILER NAMES hhc PATHS "[HKEY_CURRENT_USER\\Software\\Microsoft\\HTML Help Workshop;InstallDir]" PATH_SUFFIXES "HTML Help Workshop" )

关键点：

• NAMES hhc：CMake 在 Windows 上会自动尝试hhc、hhc.exe等候选名；
• 注册表查询：PATHS直接引用了注册表键HKEY_CURRENT_USER\Software\Microsoft\HTML Help Workshop下的InstallDir值，这是 HTML Help Workshop 安装时写入的安装目录。CMake 的find_program原生支持以[HKEY_...;ValueName]语法读取注册表路径，这是本模块最高效的定位手段；
• PATH_SUFFIXES "HTML Help Workshop"：在标准路径与注册表目录下，还会继续追加HTML Help Workshop子目录进行探测，兼容部分安装器把程序放在.../HTML Help Workshop/hhc.exe的情况。

5.2 基于编译器目录推导头文件与库

找到编译器后，模块先用get_filename_component提取其所在目录：

get_filename_component(HTML_HELP_COMPILER_PATH "${HTML_HELP_COMPILER}" PATH)

然后基于该目录去推断同根安装的头文件与库：

find_path(HTML_HELP_INCLUDE_PATH NAMES htmlhelp.h PATHS "${HTML_HELP_COMPILER_PATH}/include" "[HKEY_CURRENT_USER\\Software\\Microsoft\\HTML Help Workshop;InstallDir]/include" PATH_SUFFIXES "HTML Help Workshop/include" ) find_library(HTML_HELP_LIBRARY NAMES htmlhelp PATHS "${HTML_HELP_COMPILER_PATH}/lib" "[HKEY_CURRENT_USER\\Software\\Microsoft\\HTML Help Workshop;InstallDir]/lib" PATH_SUFFIXES "HTML Help Workshop/lib" )

可见其搜索层次依次为：

1. 编译器所在目录的兄弟子目录：<compiler_dir>/include与<compiler_dir>/lib；
2. 注册表 InstallDir 下的子目录：<InstallDir>/include与<InstallDir>/lib；
3. 追加后缀兜底：HTML Help Workshop/include、HTML Help Workshop/lib，用于应对目录结构形如<InstallDir>/HTML Help Workshop/include的安装布局。

find_path的判定标准是能找到htmlhelp.h文件，find_library的判定标准是能找到htmlhelp.lib（NAMES htmlhelp会自动尝试带前缀/后缀的候选名，如libhtmlhelp.a、htmlhelp.lib等）。

5.3 搜索策略小结

这种"先找可执行程序、再由其目录反推头文件与库"的级联搜索策略，在 CMake Find 模块中非常典型：它假设同一安装包内的程序、头文件、库位于邻近目录，从而在无需额外配置的前提下实现"一次安装、三件齐备"的自动发现。

六、官方示例与实战用法

模块文档提供了最小可用示例（Modules/FindHTMLHelp.cmake）：

find_package(HTMLHelp) message(STATUS "HTML Help Compiler found at: ${HTML_HELP_COMPILER}")

结合前文各节，一个更完整、更具工程意义的用法是：用找到的编译器在构建时把 HTML 主题编译为.chm文件：

find_package(HTMLHelp) if(HTMLHelp_FOUND) # 将 HTML 主题目录编译为帮助文件 add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/MyDoc.chm COMMAND "${HTML_HELP_COMPILER}" "${CMAKE_CURRENT_SOURCE_DIR}/MyDoc.hhp" DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/MyDoc.hhp COMMENT "Compiling HTML Help (MyDoc.chm)" ) add_custom_target(MyDoc ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/MyDoc.chm) endif()

若同时需要把帮助系统集成进应用（而非仅构建.chm），则补充头文件目录与库链接：

target_include_directories(MyApp PRIVATE ${HTML_HELP_INCLUDE_PATH}) target_link_libraries(MyApp PRIVATE ${HTML_HELP_LIBRARY})

七、使用注意事项与限制

• 平台限制：模块仅在WIN32下执行搜索，跨平台构建时需用HTMLHelp_FOUND做条件保护，避免在非 Windows 环境下引用空变量；
• 依赖安装：HTMLHelp_FOUND为TRUE的前提是 HTML Help Workshop 已正确安装，且其注册表HKCU\Software\Microsoft\HTML Help Workshop的InstallDir值有效；若用户自定义安装位置，可通过-DHTML_HELP_COMPILER=...等缓存变量手工指定路径覆盖自动探测结果；
• 弃用约束：HTML Help Workshop 已进入维护模式，.chm是存量格式；新项目建议按模块文档提示评估 Microsoft Help Viewer（.mshc）或 Web 文档工具；
• 高级缓存变量：三个路径变量被mark_as_advanced隐藏于 GUI 常规列表，如需在 cmake-gui 中手工调整，需切换到高级视图。

八、深入阅读

• 模块完整源码与内嵌文档：Modules/FindHTMLHelp.cmake
• 模块文档入口页：Help/module/FindHTMLHelp.rst
• 想了解同类 Windows 平台模块的编写范式，可对照 Help/module 目录下其他 Find 模块的文档与实现。

总体而言，FindHTMLHelp是一个小而完整的 CMake 模块：它以注册表为中心的搜索策略、三级缓存变量的设计以及Package_FOUND的判定约定，体现了 CMake 官方 Find 模块的经典模式。理解它，不仅能正确接入 HTML Help 工具链，也能举一反三地理解 CMake 模块化查找机制的通用思想。

• 构建工具
• 开发工具
• CLI