FindDoxygen

查找 Doxygen（一个源代码文档生成器）以及一些可选的辅助工具，并提供了一个命令，用于将基于 Doxygen 的文档集成到 CMake 项目中。

find_package(Doxygen [<version>] [...] [COMPONENTS <components>...] [...])

组件

其他 Doxygen 辅助工具可以通过 `find_package()` 命令的组件进行指定：find_package() 命令。

find_package(Doxygen [COMPONENTS <components>...])

支持的组件包括

doxygen

版本 3.9 中添加。

查找 `doxygen` 可执行文件。此组件即使未请求也会自动包含。

dot

版本 3.9 中添加。

查找 Graphviz 的 `dot` 工具，它用于在文档中渲染图形和图表。

mscgen

版本 3.9 中添加。

查找 Doxygen 的 `\msc` 和 `\mscfile` 命令使用的“消息图生成器”（Message Chart Generator）工具：Message Chart Generator。

dia

版本 3.9 中添加。

查找 Doxygen 的 `\diafile` 命令使用的“Dia”图编辑器：Dia。

导入的目标

此模块提供了以下 导入目标，如果请求了相应组件且找到了相关可执行文件，则会定义每个目标。

Doxygen::doxygen

版本 3.9 中添加。

导入的可执行目标，封装了 `doxygen` 可执行文件的使用需求。如果找到 Doxygen，则可用。

Doxygen::dot

版本 3.9 中添加。

导入的可执行目标，封装了 `dot` 可执行文件的使用需求。如果找到上述 `dot` 组件，则可用。

Doxygen::mscgen

版本 3.9 中添加。

导入的可执行目标，封装了 `mscgen` 可执行文件的使用需求。如果找到上述 `mscgen` 组件，则可用。

Doxygen::dia

版本 3.9 中添加。

导入的可执行目标，封装了 `dia` 可执行文件的使用需求。如果找到上述 `dia` 组件，则可用。

这些目标可以用在 `add_custom_command()` 等命令中，并且比旧的、已弃用的变量（如 `DOXYGEN_EXECUTABLE`）更受推荐。

结果变量

此模块定义了以下变量

Doxygen_FOUND

布尔值，指示是否找到（请求的版本） `doxygen` 可执行文件以及所有请求的必需组件。为了向后兼容，也设置了 `DOXYGEN_FOUND` 变量，但其布尔值为 `YES` 或 `NO`。

DOXYGEN_VERSION

找到的 Doxygen 版本（如 `doxygen --version` 报告的那样）。

命令

此模块提供以下命令

doxygen_add_docs

版本 3.9 中添加。

在构建阶段添加一个自定义目标，用于使用 Doxygen 生成文档。

doxygen_add_docs(
  <target-name>
  [<files-or-dirs>...]
  [ALL]
  [USE_STAMP_FILE]
  [WORKING_DIRECTORY <dir>]
  [COMMENT <comment>]
  [CONFIG_FILE <file>]
)

默认情况下，此便捷命令还在 CMake 配置阶段在当前二进制目录中生成一个名为 `Doxyfile.` 的配置文件。它提供了合理的默认值，因此大多数项目只需要指定输入文件或目录。可以使用以下部分所述的变量来自定义其他行为和配置。

参数为

<target-name>

要创建的用于使用 Doxygen 生成文档的目标名称。

<files-or-dirs>...

一个或多个路径（文件或目录），作为文档的输入源。

这些将传递给生成的 `Doxyfile.` 中的 `INPUT` Doxygen 配置标签。此处列出的文件也将作为底层 `add_custom_target()` 命令的 `SOURCES` 参数添加，以便它们出现在 IDE 项目的源列表中。

当使用 `USE_STAMP_FILE` 选项时，只允许文件（不允许目录、符号链接或通配符），并且每个文件在调用此命令时都必须存在。

ALL

3.12 版本新增。

将创建的文档目标添加到默认构建目标，以便它作为构建阶段的一部分自动运行。

USE_STAMP_FILE

3.16 版新增。

启用时间戳文件，以避免在源文件未更改时重新生成文档。

时间戳文件（名为 `.stamp`）由底层自定义命令在当前二进制目录中创建。

使用此选项时，`` 中的所有条目在调用此命令时都必须是现有文件（即不允许目录、符号链接或通配符）。如果任何列出的路径无效，将引发错误。

如果未使用此选项，CMake 将在每次构建 `` 目标时重新运行 Doxygen，而不管 `` 中列出的任何输入源文件是否已更改。

WORKING_DIRECTORY <dir>

默认情况下，Doxygen 的工作目录是当前源目录（CMAKE_CURRENT_SOURCE_DIR）。这与使用相对输入路径一致。

使用此选项来更改和覆盖 Doxygen 运行的目录。然后，绝对路径 `

` 将用作相对路径的基础点。

另请注意，Doxygen 的默认行为是从生成的文档中的相对路径中剥离工作目录。有关更多详细信息，请参阅 Doxygen 手册 中的 `STRIP_FROM_PATH` 配置标签。

COMMENT <comment>

如果提供了 `` 字符串，它将作为 `COMMENT` 参数传递给用于在内部创建自定义目标的底层 `add_custom_target()` 命令。当目标构建时，这会显示在构建系统的输出中。

CONFIG_FILE <file>

在 3.27 版本中新增。

如果指定，则提供的带有完整路径的文件将用作 Doxygen 配置文件，而不是默认的 `Doxyfile.`。

用于自定义 Doxygen 配置的变量

`doxygen_add_docs()` 命令生成一个包含配置标签的 Doxygen 配置文件。例如：

Doxygen.<target-name>

DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = DoxygenExample
PROJECT_NUMBER         = 1.2.3
PROJECT_BRIEF          = "Example project using Doxygen"
PROJECT_LOGO           =
OUTPUT_DIRECTORY       = /home/user/doxygen-example/build
GENERATE_HTML          = YES
GENERATE_MAN           = NO
# ...

在 CMake 中，可以通过设置形式为 `DOXYGEN_` 的输入变量来修改这些标签，其中 `` 是 Doxygen 手册 中列出的配置标签之一。

例如，要修改 `GENERATE_HTML` 和 `GENERATE_MAN` 配置标签，可以在调用 `doxygen_add_docs()` 之前设置以下变量：

CMakeLists.txt

find_package(Doxygen)

if(Doxygen_FOUND)
  set(DOXYGEN_GENERATE_HTML NO)
  set(DOXYGEN_GENERATE_MAN YES)

  doxygen_add_docs(project_docs ${PROJECT_SOURCE_DIR})
endif()

默认配置

默认情况下，`doxygen_add_docs()` 会覆盖 Doxygen 的几个设置，以更好地适应典型的 CMake 项目。除非在调用 `doxygen_add_docs()` 之前已定义，否则会明确设置以下每个变量，但有一些例外情况（如下所述）：

DOXYGEN_HAVE_DOT

如果请求并找到了 `dot` 组件，则设置为 `YES`，否则设置为 `NO`。忽略 `DOXYGEN_HAVE_DOT` 的任何现有值。

DOXYGEN_DOT_MULTI_TARGETS

由本模块设置为 `YES`（请注意，这需要比 1.8.10 更新的 `dot` 版本）。此选项仅在 `DOXYGEN_HAVE_DOT` 也设置为 `YES` 时才有意义。

DOXYGEN_GENERATE_LATEX

由本模块设置为 `NO`。

DOXYGEN_WARN_FORMAT

对于基于 Visual Studio 的生成器，这被设置为 Visual Studio IDE 识别的格式：`$file($line) : $text`。对于所有其他生成器，Doxygen 的默认值不会被覆盖。

DOXYGEN_PROJECT_NAME

填充为当前项目的名称（即 PROJECT_NAME）。

DOXYGEN_PROJECT_NUMBER

填充为当前项目的版本（即 PROJECT_VERSION）。

DOXYGEN_PROJECT_BRIEF

填充为当前项目的描述（即 PROJECT_DESCRIPTION）。

DOXYGEN_INPUT

此变量会自动用传递给 `doxygen_add_docs()` 的文件和目录列表进行填充。为了与其他内置命令（如 `add_executable()`、`add_library()` 和 `add_custom_target()`）保持一致，项目不应手动设置此变量。如果项目设置了名为 `DOXYGEN_INPUT` 的变量，它将被忽略并发出警告。

DOXYGEN_RECURSIVE

由本模块设置为 `YES`。

DOXYGEN_EXCLUDE_PATTERNS

如果 `doxygen_add_docs()` 的 `` 参数包含目录，此变量将指定用于从这些目录中排除文件的模式。默认情况下，会添加以下模式以确保 CMake 特定的文件和目录不包含在输入中。如果项目设置了此变量，则这些内容将与这些附加模式合并，而不是替换它们。

*/.git/*
*/.svn/*
*/.hg/*
*/CMakeFiles/*
*/_CPack_Packages/*
DartConfiguration.tcl
CMakeLists.txt
CMakeCache.txt

DOXYGEN_OUTPUT_DIRECTORY

由本模块设置为 CMAKE_CURRENT_BINARY_DIR。如果项目为此提供了自己的值，并且它是一个相对路径，则它将相对于当前二进制目录（CMAKE_CURRENT_BINARY_DIR）进行解释。这是必要的，因为 Doxygen 通常会从源树中的一个目录运行，以便相对源路径按预期工作。如果此目录不存在，则在执行 Doxygen 之前会递归创建它。

列表

许多 Doxygen 配置标签接受列表值，Doxygen 要求它们用空格分隔，而在 CMake 中，列表是项目号分隔的项目字符串（分号）。

`doxygen_add_docs()` 专门检查以下 Doxygen 配置标签，并在设置时将它们关联的 CMake `DOXYGEN_` 变量值转换为 Doxygen 格式的列表：

ABBREVIATE_BRIEF ALIASES CITE_BIB_FILES DIAFILE_DIRS DOTFILE_DIRS DOT_FONTPATH ENABLED_SECTIONS EXAMPLE_PATH EXAMPLE_PATTERNS EXCLUDE EXCLUDE_PATTERNS EXCLUDE_SYMBOLS EXPAND_AS_DEFINED EXTENSION_MAPPING EXTRA_PACKAGES EXTRA_SEARCH_MAPPINGS FILE_PATTERNS FILTER_PATTERNS FILTER_SOURCE_PATTERNS

HTML_EXTRA_FILES HTML_EXTRA_STYLESHEET IGNORE_PREFIX IMAGE_PATH INCLUDE_FILE_PATTERNS INCLUDE_PATH INPUT LATEX_EXTRA_FILES LATEX_EXTRA_STYLESHEET MATHJAX_EXTENSIONS MSCFILE_DIRS PLANTUML_INCLUDE_PATH PREDEFINED QHP_CUST_FILTER_ATTRS QHP_SECT_FILTER_ATTRS STRIP_FROM_INC_PATH STRIP_FROM_PATH TAGFILES TCL_SUBST

例如，要自定义 Doxygen 的文件模式，可以在 CMake 中设置一个通常的分号分隔列表：

CMakeLists.txt

find_package(Doxygen)

if(Doxygen_FOUND)
  set(DOXYGEN_FILE_PATTERNS *.c *.cxx *.h *.hxx)
  doxygen_add_docs(example_docs ${CMAKE_CURRENT_SOURCE_DIR} ALL)
endif()

这将生成一个在生成的配置文件中由空格分隔的 Doxygen 模式列表：

Doxyfile.<target-name>

# ...
FILE_PATTERNS          = *.c *.cxx *.h *.hxx

自动引用

如果 Doxygen 的单值标签包含空格，则其值必须用双引号（`"..."`）括起来。`doxygen_add_docs()` 在生成 `Doxyfile` 时会自动引用以下 Doxygen 标签的值（如果它们至少包含一个空格）：

CHM_FILE DIA_PATH DOCBOOK_OUTPUT DOCSET_FEEDNAME DOCSET_PUBLISHER_NAME DOT_FONTNAME DOT_PATH EXTERNAL_SEARCH_ID FILE_VERSION_FILTER GENERATE_TAGFILE HHC_LOCATION HTML_FOOTER HTML_HEADER HTML_OUTPUT HTML_STYLESHEET INPUT_FILTER LATEX_FOOTER LATEX_HEADER LATEX_OUTPUT LAYOUT_FILE MAN_OUTPUT

MAN_SUBDIR MATHJAX_CODEFILE MSCGEN_PATH OUTPUT_DIRECTORY PERL_PATH PLANTUML_JAR_PATH PROJECT_BRIEF PROJECT_LOGO PROJECT_NAME QCH_FILE QHG_LOCATION QHP_CUST_FILTER_NAME QHP_VIRTUAL_FOLDER RTF_EXTENSIONS_FILE RTF_OUTPUT RTF_STYLESHEET_FILE SEARCHDATA_FILE USE_MDFILE_AS_MAINPAGE WARN_FORMAT WARN_LOGFILE XML_OUTPUT

DOXYGEN_VERBATIM_VARS

3.11 版本新增。

一个 CMake 输入变量，用于 `doxygen_add_docs()` 来指定 Doxygen 输入变量列表（包括其前缀 `DOXYGEN_`），这些变量的值应在不进行自动引用的情况下传递给生成的 `Doxyfile` 配置。

使用此变量时，项目负责确保这些变量的值在直接放入生成的 `Doxyfile` 配置时是有意义的。对于列表变量，项仍然在输出中用空格分隔，但不对单个项进行引用。

对于某些 Doxygen 标签，例如 `ALIASES`，`doxygen_add_docs()` 的自动引用可能会干扰正确的语法（例如，嵌入式引号）。

例如，以下代码将引用 `DOXYGEN_PROJECT_BRIEF`，但会跳过 `DOXYGEN_ALIASES` 列表中的每个项（使用括号语法以方便处理嵌入式引号）：

CMakeLists.txt

find_package(Doxygen)

if(Doxygen_FOUND)
  set(DOXYGEN_PROJECT_BRIEF "String with spaces")
  set(
    DOXYGEN_ALIASES
    [[somealias="@some_command param"]]
    "anotherAlias=@foobar"
  )
  set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)

  add_doxygen_docs(project_docs ${PROJECT_SOURCE_DIR})
endif()

生成的 `Doxyfile` 配置将包含以下行：

Doxyfile.project_docs

PROJECT_BRIEF = "String with spaces"
ALIASES       = somealias="@some_command param" anotherAlias=@foobar

已弃用变量

为了与 CMake 的早期版本兼容，还定义了以下变量，但它们已弃用，不应再使用：

DOXYGEN_EXECUTABLE

自 3.9 版本起已弃用： 请使用 `Doxygen::doxygen` 导入的目标，而不是直接引用 `doxygen` 可执行文件。

包含 `doxygen` 命令路径的缓存变量。

DOXYGEN_DOT_FOUND

自 3.9 版本起已弃用。

布尔结果变量，指示是否找到 `dot` 可执行文件。

DOXYGEN_DOT_EXECUTABLE

自 3.9 版本起已弃用： 请使用 `Doxygen::dot` 导入的目标，而不是直接引用 `dot` 可执行文件。

包含 `dot` 命令行可执行文件路径的缓存变量。

DOXYGEN_DOT_PATH

自 3.9 版本起已弃用。

结果变量，包含 `dot` 可执行文件所在的目录的路径（如 `DOXYGEN_DOT_EXECUTABLE` 中报告的）。该路径可能带有正斜杠，即使在 Windows 上也是如此，并且不适合直接替换到 `Doxyfile.in` 模板中。如果需要此值，请获取 `Doxygen::dot` 目标的 `IMPORTED_LOCATION` 属性，并使用 `get_filename_component()` 来提取该路径的目录部分。还可以考虑使用 `file(TO_NATIVE_PATH)` 来为 Doxygen 配置文件准备路径。

DOXYGEN_SKIP_DOT

自 3.9 版本起已弃用。

在 `find_package(Doxygen COMPONENTS ...)` 中指定组件时，此提示变量不起作用。在向后兼容模式下（即不指定组件时），它可以防止此查找模块搜索 Graphviz 的 `dot` 工具。

示例

示例：查找 Doxygen

查找 Doxygen

find_package(Doxygen)

或者，查找 Doxygen 并指定所需的最低版本：

find_package(Doxygen 1.9)

或者，将 Doxygen 标记为必需（如果未找到，处理将停止并显示错误消息）：

find_package(Doxygen REQUIRED)

或者，将 Doxygen 标记为必需，并将 `dot` 工具作为必需组件，将 `mscgen` 和 `dia` 工具作为可选组件：

find_package(Doxygen REQUIRED COMPONENTS dot OPTIONAL_COMPONENTS mscgen dia)

示例：在 CMake 中使用 Doxygen

以下示例演示了如何在构建阶段查找 Doxygen 并从源文件创建文档。项目构建后，生成的文档文件将位于项目二进制目录内的 `html` 目录中：

CMakeLists.txt

cmake_minimum_required(VERSION 3.24)
project(
  DoxygenExample
  DESCRIPTION "Example project using Doxygen"
  VERSION 1.2.3
)

add_executable(example example.c)

find_package(Doxygen)

if(Doxygen_FOUND)
  doxygen_add_docs(project_docs example.c ALL USE_STAMP_FILE)
endif()

example.c

/**
 * @file example.c
 * @brief A simple example to demonstrate Doxygen.
 */

#include <stdio.h>

/**
 * @brief Calculates the sum of two integers.
 *
 * @param a First integer.
 * @param b Second integer.
 * @return Sum of a and b.
 *
 * @par Example
 * @code
 * int result = sum(3, 4);
 * printf("%d\n", result); // Outputs: 7
 * @endcode
 */
int sum(int a, int b) { return a + b; }

/**
 * @brief Main function.
 *
 * @return 0 on success.
 */
int main(void)
{
  int result = sum(5, 7);
  printf("Result: %d\n", result);
  return 0;
}

示例：使用变量配置 Doxygen

在以下示例中，Doxygen 配置使用 CMake 变量进行自定义。该配置在使用目录作为源输入（CMAKE_CURRENT_SOURCE_DIR）时设置文件模式，启用用于在浅色和深色模式之间切换的主题切换，在构建阶段抑制 Doxygen 的标准输出，将一个 Markdown 文件指定为主页面，并禁用有关未记录代码的警告：

find_package(Doxygen)

if(Doxygen_FOUND)
  set(DOXYGEN_FILE_PATTERNS *.c *.cxx *.md)
  set(DOXYGEN_HTML_COLORSTYLE "TOGGLE")
  set(DOXYGEN_QUIET YES)
  set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
  set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)

  doxygen_add_docs(example_docs ${CMAKE_CURRENT_SOURCE_DIR} ALL)
endif()

示例：自定义配置文件

在以下示例中，在调用 `doxygen_add_doxs()` 之前，在当前二进制目录（CMAKE_CURRENT_BINARY_DIR）中创建了一个自定义 `Doxyfile` 配置文件。这允许根据需要自定义项目特定的配置标签：

CMakeLists.txt

find_package(Doxygen)

if(Doxygen_FOUND)
  configure_file(Doxyfile.in Doxyfile)

  doxygen_add_doxs(
    example_docs
    foo.c bar.c
    ALL
    USE_STAMP_FILE
    COMMENT "Generating project documentation with custom Doxyfile"
    CONFIG_FILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
  )
endif()

Doxyfile.in

PROJECT_NAME           = "Customized project name"
OUTPUT_DIRECTORY       = "@CMAKE_CURRENT_BINARY_DIR@"
# ...