默认构建CMake项目时同步生成Doxygen文档的需求与问题

Got it, let's tackle this problem properly. You want Doxygen docs to build by default alongside your project when running make, but not re-run during make install, and you want docs to compile in parallel with your executable (no unnecessary dependencies). Here's the clean, idiomatic CMake approach to make this happen:

Step 1: Set Up Doxygen Detection & Configuration #

First, we'll locate Doxygen and configure its settings (using a template is the most flexible way, but you can also hardcode settings if you prefer):

# Find Doxygen (fail if not present; use REQUIRED QUIET if you want a fallback)
find_package(Doxygen REQUIRED)

# Optional: Add a toggle to let users disable doc builds if needed
option(BUILD_DOC "Build API documentation with Doxygen" ON)

if(BUILD_DOC)
    # Configure a Doxyfile template (create Doxyfile.in in your source directory first)
    # Replace placeholders like @PROJECT_NAME@, @PROJECT_VERSION@ in the template with CMake variables
    configure_file(
        ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
        ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
        @ONLY
    )

Step 2: Create a Parallel-Friendly Doc Target #

Now we'll make a custom target that builds docs by default, but doesn't tie itself to your executable or the install process:

# Create the doc target, mark it as part of the "ALL" group (so `make` runs it by default)
    add_custom_target(doc ALL
        COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
        COMMENT "Generating API docs with Doxygen..."
        VERBATIM
        # No DEPENDS clause here! That's the key to enabling parallel builds
    )
endif()

Step 3: (Optional) Install Docs Without Re-Generating Them #

If you want to install the generated docs, add this—note it won't trigger a re-build of docs during make install, it just copies existing files:

# Only install docs if we built them
if(BUILD_DOC)
    install(
        DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html  # Adjust to match your Doxygen output directory
        DESTINATION share/doc/${PROJECT_NAME}
        OPTIONAL  # Skip installation if the directory doesn't exist (e.g., user manually skipped builds)
    )
endif()

Why This Fixes Your Original Issues #

• No install-time regeneration: The doc target is part of ALL, so it runs automatically on make, but we never add it as a dependency to the install target. The install step only copies pre-generated files, not re-runs Doxygen.
• Parallel builds enabled: Since we didn't add DEPENDS your_executable_target to the doc target, CMake recognizes it can build docs and your code simultaneously—no waiting for binaries to finish before starting Doxygen.

Quick Additional Tips #

• Make sure your Doxyfile.in template uses CMake variables (like @PROJECT_NAME@) for dynamic values instead of hardcoding project details.
• If you don't want docs to build by default, just set option(BUILD_DOC "Build docs" OFF)—users can then run make doc manually when they need updated documentation.

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