寻找氧气¶

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

点: Graphviz dot 实用程序用于呈现各种图形。
mscgen: `消息图表生成器<https://www.mcternan.me.uk/mscgen/>`_ Doxygen 的``msc`` 和``mscfile`` 命令使用的实用程序。
直径: 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”可执行文件，则为真。

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])

该函数构造一个 Doxyfile 并定义一个在生成的文件上运行 Doxygen 的自定义目标。列出的文件和目录用作生成的 Doxyfile 的``INPUT``，它们可以包含通配符。任何明确列出的文件也将作为自定义目标的“SOURCES”添加，因此它们将显示在 IDE 项目的源列表中。

为了使相对输入路径按预期工作，默认情况下 Doxygen 命令的工作目录将是当前源目录（即 CMAKE_CURRENT_SOURCE_DIR）。这可以用 WORKING_DIRECTORY 选项覆盖，以更改用作相对基点的目录。另请注意，Doxygen 的默认行为是从生成的文档中的相对路径中剥离工作目录（请参阅``STRIP_FROM_PATH```Doxygen 配置选项 <https://www.doxygen.nl/manual/config.html>`_详情）。

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

在 3.12 版本加入: 如果设置了 ALL ，目标将被添加到默认构建目标。

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

生成的 Doxyfile 的内容可以通过在调用 doxygen_add_docs() 之前设置 CMake 变量来定制。任何名称为 DOXYGEN_<tag> 形式的变量都将用其值替换 Doxyfile 中相应的 <tag> 配置选项。有关支持的配置选项的完整列表，请参阅`Doxygen 文档 <https://www.doxygen.nl/manual/config.html>`_。

Doxygen 的一些默认设置被覆盖，以便为 CMake 项目提供更合适的行为。除非变量在调用 doxygen_add_docs() 之前已经有一个值，否则将显式设置以下各项（注意一些例外）：

DOXYGEN_HAVE_DOT¶: 如果请求了“点”组件并且找到了，则设置为“是”，否则设置为“否”。 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() 和 :command: add_custom_target。如果项目设置了名为 DOXYGEN_INPUT 的变量，它将被忽略并发出警告。

DOXYGEN_RECURSIVE¶: 由该模块设置为“是”。

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 变量的内容转换为所需的形式（如果已设置）。对于此处指定的 Doxygen 设置，CMake 变量被命名为 DOXYGEN_<name>。

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 列表中的每个项目（ bracket syntax 也可以是用于使使用嵌入式引号更容易）：

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¶: 如果找到“点”可执行文件，则为真。

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

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

弃用的提示变量¶

自 3.9 版本弃用.

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

寻找氧气¶

功能¶

弃用的结果变量¶

弃用的提示变量¶

目录

上一主题

下一主题

本页