FindDoxygen

Doxygen 是一个文档生成工具 (参见 https://doxygen.cpp.org.cn)。此模块查找 Doxygen 及其支持的一些可选工具

dot

Graphviz dot 实用程序，用于渲染各种图形。

mscgen

Message Chart Generator 实用程序，供 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 将作为用于在内部创建自定义目标的 add_custom_target() 命令的 COMMENT 传递。

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（请注意，这需要 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 特定的文件和目录不包含在输入中。如果项目设置了 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

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

已弃用的提示变量

自 3.9 版本起已弃用。

DOXYGEN_SKIP_DOT

此变量对于 find_package 的组件形式无效。在向后兼容模式下（即没有组件列表），它可以防止查找器模块搜索 Graphviz 的 dot 实用程序。