MSYS2环境下CMake调用Doxygen生成API文档的路径处理问题咨询

疑问解答 #

1. file(TO_NATIVE_PATH) 在MSYS2环境下生成带反斜杠转义空格的路径属于预期行为，这是CMake为适配MSYS2 Shell转义规则设计的特性。问题根源是3.26版本前的FindDoxygen模块没有区分「Shell转义路径」和「Doxygen配置文件路径」的语义差异，直接把适配Shell的转义路径写入了Doxyfile，而Doxygen配置文件本身不识别Shell风格的反斜杠转义，仅支持用双引号包裹带空格的路径。
2. 不存在遗漏的核心配置，你不需要绕过FindDoxygen模块，通过CMake原生的变量覆盖机制就能合规修复问题，完全符合CMake使用规范。

规范修复方案 #

1. 修复dot工具查找失败问题 #

在调用doxygen_add_docs前添加如下逻辑，覆盖FindDoxygen生成的DOXYGEN_DOT_PATH变量，去掉转义反斜杠并用双引号包裹路径适配Doxygen的解析规则：

if(MSYS AND DOXYGEN_DOT_FOUND)
    # 移除路径中的Shell转义反斜杠
    string(REPLACE "\ " " " DOXYGEN_DOT_PATH "${DOXYGEN_DOT_PATH}")
    # 用双引号包裹带空格的路径，适配Doxygen配置文件规则
    set(DOXYGEN_DOT_PATH "\"${DOXYGEN_DOT_PATH}\"" CACHE INTERNAL "Dot path for Doxygen config")
endif()

2. 规范集成输出目录转换逻辑 #

你之前用cygpath转换路径的方案可以直接集成到CMake脚本中，不需要手动处理：

if(MSYS)
    # 调用cygpath将Windows格式路径转换为MSYS2 Doxygen识别的Unix格式路径
    execute_process(
        COMMAND cygpath -u "${CMAKE_CURRENT_BINARY_DIR}/doc"
        OUTPUT_VARIABLE DOXYGEN_OUTPUT_DIRECTORY
        OUTPUT_STRIP_TRAILING_WHITESPACE
    )
endif()

更简单的替代方案 #

如果不想修改CMake逻辑，你可以直接卸载当前MSYS2仓库中的原生Doxygen和Windows版GraphViz，安装MinGW编译的对应套件：

pacman -S mingw-w64-x86_64-doxygen mingw-w64-x86_64-graphviz

MinGW版本的Doxygen和GraphViz原生支持Windows格式路径，不需要做任何路径适配就能正常运行。
如果可以升级CMake版本，将CMake升级到3.26及以上版本，官方已经修复了FindDoxygen模块在MSYS2环境下的路径转义问题，也可以直接解决dot查找失败的问题。

内容的提问来源于stack exchange，提问作者user2169513