FindDoxygen¶

Doxygen 是一个文档生成工具（请参阅 https://www.doxygen.nl）。此模块查找 Doxygen 和一些它支持的可选工具

dot: Graphviz dot 工具用于呈现各种图形。
mscgen: 消息图表生成器由 Doxygen 的 \msc 和 \mscfile 命令使用。
dia: Dia 由 Doxygen 的 \diafile 命令使用的图表编辑器。

版本 3.9 中已添加：可在 find_package() 命令中使用这些工具作为组件。例如

# Require dot, treat the other components as optional
find_package(Doxygen
             REQUIRED dot
             OPTIONAL_COMPONENTS mscgen dia)

此模块定义了以下变量

DOXYGEN_FOUND¶: 如果找到 doxygen 可执行文件，则为 True。

DOXYGEN_VERSION¶: 由 doxygen --version 报告的版本。

版本 3.9 中已添加：此模块为 Doxygen 和找到的每个组件定义 IMPORTED 目标。它们可用作自定义命令等的一部分，并且优先于 DOXYGEN_EXECUTABLE 等旧式（现已弃用）变量。如果找到相应的可执行文件，将定义以下导入目标（仅当请求该组件时才定义组件导入目标）

Doxygen::doxygen
Doxygen::dot
Doxygen::mscgen
Doxygen::dia

函数¶

doxygen_add_docs¶

版本 3.9 中已添加。

此函数旨在为使用 Doxygen 生成文档的目标提供便利。它的目标是提供明智的默认值，以便项目通常只提供输入文件和目录，这足以产生明智的结果。此函数支持自定义用于构建文档的 Doxygen 配置的能力。

doxygen_add_docs(targetName
    [filesOrDirs...]
    [ALL]
    [USE_STAMP_FILE]
    [WORKING_DIRECTORY dir]
    [COMMENT comment]
    [CONFIG_FILE filename])

此函数构建 Doxyfile 并定义一个自定义目标，在该生成的文件上运行 Doxygen。所列文件和目录用作生成 Doxyfile 的 INPUT，并且它们可以包含通配符。任何明确列出的文件都将作为自定义目标的 SOURCES 添加，以便它们出现在 IDE 项目的源代码列表中。

使相对输入路径按预期的那样起作用，因此默认情况下，Doxygen 命令的工作目录是当前源目录（即 CMAKE_CURRENT_SOURCE_DIR）。可以使用 WORKING_DIRECTORY 选项覆盖，以更改用作相对基点的目录。还需要注意，Doxygen 的默认行为是从生成的文档中剥离工作目录的相对路径（有关详细信息，请参阅 STRIP_FROM_PATH Doxygen 配置选项）。

如果提供了，可选的 comment 将作为 COMMENT 传递给 add_custom_target() 命令，该命令用于在内部创建自定义目标。

在 3.27 版本中添加：如果设置了 CONFIG_FILE，则将使用提供完整路径的给定文件作为 doxygen 配置文件

在 3.12 版本中添加：如果设置了 ALL，则此目标将添加到默认构建目标。

在 3.16 版本中添加：如果设置了 USE_STAMP_FILE，则此函数定义的自定义命令每当重新运行 doxygen 时，均会在当前二进制目录中创建名为 <targetName>.stamp 的图章文件。如果存在此选项，则 <filesOrDirs> 中的所有项都必须是文件（即没有目录、符号链接或通配符），并且在调用 doxygen_add_docs() 时每个文件都必须存在。如果在给出 USE_STAMP_FILE 时，找到任何列出的项缺失或不是文件，都将引发错误。将对每个文件创建依存关系，以便仅在更新某个文件时才重新运行 doxygen。如果没有 USE_STAMP_FILE 选项，则无论 <filesOrDirs> 中列出的任何内容是否已更改，只要构建 <targetName> 目标，都始终会重新运行 doxygen。

可以通过在调用 doxygen_add_docs() 之前设置 CMake 变量来定制生成的 Doxyfile 的内容。名为 DOXYGEN_<tag> 的任何变量都会将其值替换为 Doxyfile 中相应的 <tag> 配置选项。请参阅 Doxygen 文档，了解受支持配置选项的完整列表。

将部分 Doxygen 默认值改写为，以便为 CMake 项目提供更多适合行为。除非变量在调用 doxygen_add_docs() 之前已具有值（带有一些注明的例外情况），否则将明确设置各个以下变量

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

DOXYGEN_DOT_MULTI_TARGETS¶: 此模块设为 YES（注意这需要一个 dot 版本，该版本高于 1.8.10）。仅当 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 特有的文件和目录未包含在输入中。如果项目设置 DOXYGEN_EXCLUDE_PATTERNS，这些内容将与这些附加模式合并，而不是替换它们

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

DOXYGEN_OUTPUT_DIRECTORY¶: 此模块将此变量设置为 CMAKE_CURRENT_BINARY_DIR。请注意，如果项目为此提供自己的值且它是相对路径，则它将转换为相对于当前二进制目录的绝对路径。这是必需的，因为 doxygen 通常将从源代码树中的目录运行，以便相对源代码路径按照预期工作。如果此目录不存在，将在执行 doxygen 命令之前对其进行递归创建。

要更改任何这些默认值或覆盖任何其他 Doxygen 配置选项，请在调用 doxygen_add_docs() 之前设置相关变量。例如：

set(DOXYGEN_GENERATE_HTML NO)
set(DOXYGEN_GENERATE_MAN YES)

doxygen_add_docs(
    doxygen
    ${PROJECT_SOURCE_DIR}
    COMMENT "Generate man pages"
)

许多 Doxygen 配置选项接受值列表，但 Doxygen 要求它们以空格分隔。CMake 变量以字符串形式保存列表，各项目由分号分隔，因此需要执行转换。 doxygen_add_docs() 命令专门检查以下 Doxygen 配置选项，并在设置后将其关联的 CMake 变量的内容转换为所需的形式。CMake 变量被命名为 DOXYGEN_<name> 以下面指定的 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 选项包含至少一个空格，它们将自动加上引号

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

3.11 版中添加：在某些情况下，对于特定的配置选项来说，最好不要让 doxygen_add_docs() 自动加上引号，例如 ALIASES，后者可能需要包含其自己的嵌入式引号。 DOXYGEN_VERBATIM_VARS 变量可用于指定不应加上引号的 Doxygen 变量列表（包括前导 DOXYGEN_ 前缀）。然后这个项目负责确保在变量值直接放入 Doxygen 输入文件时，这些变量的值是合理的。对于列表变量，列表项仍然用空格分隔，只是跳过了自动加引号。例如，以下内容允许 doxygen_add_docs() 为 DOXYGEN_PROJECT_BRIEF 添加引号，但为 DOXYGEN_ALIASES 列表中的每个项添加引号（也可以使用方括号语法来简化对嵌入式引号的使用）

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

生成的 Doxyfile 将包含以下行

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

已弃用的结果变量¶

3.9 版之后已弃用。

为了与 CMake 的前一个版本兼容，还定义了以下变量，但它们已被弃用，不应再使用

DOXYGEN_EXECUTABLE¶: 指向 doxygen 命令的路径。如果项目需要直接引用 doxygen 可执行文件，则应该使用 Doxygen::doxygen 导入目标。

DOXYGEN_DOT_FOUND¶: 如果找到 dot 可执行文件，则为 True。

DOXYGEN_DOT_EXECUTABLE¶: 指向 dot 命令的路径。如果项目需要直接引用 dot 可执行文件，则应该使用 Doxygen::dot 导入目标。

DOXYGEN_DOT_PATH¶: 在 DOXYGEN_DOT_EXECUTABLE 中报告的包含 dot 可执行文件的目录路径。即使是在 Windows 上，路径也可能具有正斜杠，并且不适合直接替换为 Doxyfile.in 模板。如果您需要这个值，请获取 IMPORTED_LOCATION 的 Doxygen::dot 目标属性并使用 get_filename_component() 提取该路径的目录部分。您还可能希望考虑使用 file(TO_NATIVE_PATH) 为 Doxygen 配置文件准备路径。

已弃用的提示变量¶

3.9 版之后已弃用。

DOXYGEN_SKIP_DOT¶: 此变量对 find_package 的组件形式没有任何影响。在向后兼容模式（即，没有组件列表）下，它会阻止搜索器模块搜索 Graphviz 的 dot 实用程序。

FindDoxygen¶

函数¶

已弃用的结果变量¶

已弃用的提示变量¶

目录

上一主题

下一主题

此页