CMake：如何对具有多个目标的项目使用 doxygen_add_docs() 并在构建期间生成

Question

我有一个具有以下结构的项目：

myproject/
├─ build/
├─ cmake/
│  └─ DoxygenFun.cmake
├─ docs/
├─ src/
│  ├─ CMakeLists.txt
│  ├─ superlib/
│  │  ├─ CMakeLists.txt
│  │  ├─ lib1/
│  │  │  ├─ include/
│  │  │  │  └─ lib1.h
│  │  │  ├─ lib1.cpp
│  │  │  └─ CMakeLists.txt
│  │  └─ lib2/
│  │     ├─ include/
│  │     │  └─ lib2.h
│  │     ├─ lib2.cpp
│  │     └─ CMakeLists.txt
│  └─ exec/
│     ├─ main.cpp
│     ├─ aux.h
│     └─ CMakeLists.txt
└─ CMakeLists.txt

superlib

有两个库

lib1

和

lib2

在 CMake 中用

add_library()

定义。

lib2

取决于

lib1

。主要可执行文件

exec

（用

add_executable()

定义）取决于

lib2

。

CMakeLists.txt

中的

src/

文件仅包含

add_subdirectory()

和

superlib

。并且

exec

中的

CMakeLists.txt

文件仅包含

src/superlib/

和

add_subdirectory()

的

lib1

。我有一个用

lib2

编写的函数，它获取目标名称及其路径，设置一些

DoxygenFun.cmake

变量并调用

DOXYGEN_

。它是：doxygen_add_docs()

我的顶级

function(DoxygenFun target input)
  set(DOXYGEN_HTML_OUTPUT            ${PROJECT_BINARY_DIR}/docs) # ?????
  set(DOXYGEN_JAVADOC_AUTOBRIEF      YES)
  set(DOXYGEN_GENERATE_HTML          YES)
  set(DOXYGEN_HAVE_DOT               YES)

# other DOXYGEN_... options

  doxygen_add_docs(doxygen-${target}
      ${input}
      ALL  # add to the default build target
      COMMENT "Generate HTML documentation"
      )
endfunction()

是：

CMakeLists.txt

与目标关联的每个内部 

cmake_minimum_required(VERSION 3.24)
project(myproject VERSION 0.1.0 LANGUAGES CXX)

list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")

find_package(Doxygen REQUIRED dot)
include(DoxygenFun)

add_subdirectory(src bin)

add_custom_target(doc_doxygen ALL
    COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_BINARY_DIR}/docs
    WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
)

文件都有一个附加的：

CMakeLists.txt

其中 

# ...
DoxygenFun(targetname ${CMAKE_CURRENT_SOURCE_DIR})

是我为

targetname

、

lib1

或

lib2

定义的目标名称。我想在构建过程中在

exec

中生成整个项目的文档。但是，我的函数

{PROJECT_BINARY_DIR}/docs

似乎为每个目标在

DoxygenFun

中生成一个

Doxyfile

，而不是为

${CMAKE_CURRENT_BINARY_DIR}

内的整个项目生成一个

Doxyfile

。那么我运行

{PROJECT_BINARY_DIR}/docs

的自定义命令不会执行任何操作。如果我从终端单独运行每个生成的

${DOXYGEN_EXECUTABLE}

，似乎

Doxyfile

中生成的html文件会为每个目标相互覆盖，而不是为整个项目生成单个html文件。也许我完全误解了如何使用

{PROJECT_BINARY_DIR}/docs

？我是否需要遍历所有源文件和头文件并将它们仅传递给一个

doxygen_add_docs()

？目标是什么？我尝试过在网上的示例中寻找答案，但他们似乎要么只针对结构简单的项目（例如

Halide 的 github 存储库

）执行此操作，要么不使用 doxygen_add_docs()，这需要使用

doxygen_add_docs()

和 (据我了解）已经过时了。此外，

configure_file()

中是否应该有

CMakeLists.txt

（以及主

docs/

文件中的附加

add_subdirectory(docs)

）？PS.：我从 Rafal Swidzinski 的《Modern CMake for C++》一书中获取了

CMakeLists.txt

模块。不过，他没有展示如何在构建过程中制作文档，仅展示了安装过程。

Answer 1

DoxygenFun.cmake

的方法。

首先，我误解了

FindDoxygen

的文档。我认为 doxygen_add_files() 的

targetName

应该是针对已经存在的目标。仔细重新阅读后，它指出构建了一个名为

doxygen_add_files()

的新目标。我找不到一种方法使这个新目标成为构建的一部分。在

targetName

中添加

ALL

选项不起作用。尽管如此，在 CLion 中，可以运行此函数生成的目标来生成文档。其次，在文档中写道，

doxygen_add_files()

设置为

RECURSIVE

中的

YES

。因此，您只需将项目源目录传递给

doxygen_add_files()

，doxygen 就可以生成整个项目的文档。这样做的好处是能够使用

doxygen_add_files()

文件作为带有变量

README.md

的文档主页。请注意，

DOXYGEN_USE_MDFILE_AS_MAINPAGE

可用于排除文件夹，例如

DOXYGEN_EXCLUDE_PATTERNS

或

*/extern/*

用于包含使用

*/deps/*

获取的外部依赖项的文件夹。我已经删除了

FetchContent

文件以及

DoxygenFun.cmake

函数的所有用法。在

DoxygenFun

内我添加了一个

myproject/docs

文件，其中包含：CMakeLists.txt

那么主要的

find_package(Doxygen REQUIRED dot)

set(DOXYGEN_HTML_OUTPUT            ${PROJECT_BINARY_DIR}/docs/html)
set(DOXYGEN_JAVADOC_AUTOBRIEF      YES)
set(DOXYGEN_GENERATE_HTML          YES)
set(DOXYGEN_HAVE_DOT               YES)
set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)  # requires a README.md in /myproject/

# other DOXYGEN_... options

doxygen_add_docs(docs_target
  ${PROJECT_SOURCE_DIR}
  ALL  # does not seem to work
  COMMENT "Generate HTML documentation"
)

就变成：

CMakeLists.txt

在 CLion 中，我可以构建 

cmake_minimum_required(VERSION 3.24)
project(myproject VERSION 0.1.0 LANGUAGES CXX)

list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")

add_subdirectory(src bin)

add_subdirectory(docs)

来生成文档。

我想知道如何将它与构建一起运行...