如何在CMake中无需新增目标，构建主项目时自动生成Doxygen文档

要让构建主目标my-project时自动生成Doxygen文档，无需新增单独的文档目标，你可以通过将文档生成命令关联到主目标来实现，具体有两种常用方案：

方案一：主目标构建完成后自动生成文档（POST_BUILD） #

这种方式会在my-project编译完成后立即执行Doxygen命令，适合希望文档随二进制产物同步更新的场景：

option(BUILD_DOC "Build documentation" ON)

find_package(Doxygen)

# 仅当找到Doxygen且开启BUILD_DOC时执行
if (DOXYGEN_FOUND AND BUILD_DOC)
    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.out)
    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)

    # 给主目标my-project添加POST_BUILD命令
    add_custom_command(TARGET my-project POST_BUILD
            COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
            COMMENT "Generating Doxygen documentation..."
            VERBATIM)
endif()

方案二：主目标构建前先生成文档 #

如果需要文档生成完成后再编译主项目（比如文档依赖最新代码注释），可以通过自定义输出产物并让主目标依赖它：

option(BUILD_DOC "Build documentation" ON)

find_package(Doxygen)

if (DOXYGEN_FOUND AND BUILD_DOC)
    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.out)
    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)

    # 定义文档生成命令，指定输出产物（以html目录的首页为例）
    add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
            COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
            MAIN_DEPENDENCY ${DOXYGEN_OUT}
            DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
            COMMENT "Generating Doxygen documentation..."
            VERBATIM)

    # 让主目标my-project依赖文档产物，确保构建前先生成文档
    add_dependencies(my-project ${CMAKE_CURRENT_BINARY_DIR}/html/index.html)
endif()

关键说明 #

• 你之前删除add_custom_target后失败的原因：add_custom_target是单独定义了一个可执行目标，但删除后没有把文档生成逻辑绑定到my-project目标上，CMake无法感知要在构建主项目时执行该命令。
• 确保你的CMakeLists.txt中已经通过add_executable(my-project ...)或add_library(my-project ...)定义了主目标，否则上述代码会报错。
• 通过BUILD_DOC选项可以快速开关文档生成功能，无需修改代码。

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