FindDoxygen

Doxygen — это инструмент для генерации документации (см. https://www.doxygen.nl). Этот модуль ищет Doxygen и некоторые дополнительные поддерживаемые инструменты:

dot

Graphviz — утилита, используемая для визуализации различных графиков.

mscgen

Message Chart Generator — утилита, используемая командами Doxygen \msc и \mscfile.

dia

Dia — редактор диаграмм, используемый командой Doxygen \diafile.

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

Этот модуль определяет следующие переменные:

DOXYGEN_FOUND

Истина, если был найден исполняемый файл doxygen.

DOXYGEN_VERSION

Версия, сообщенная doxygen --version.

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 для этого сгенерированного файла. Указанные файлы и каталоги используются в качестве INPUT сгенерированной Doxyfile, и они могут содержать подстановочные знаки. Любые файлы, которые указаны явно, также будут добавлены в качестве SOURCES пользовательской цели, поэтому они будут отображаться в списке источников проекта IDE.

Для того, чтобы относительные пути к входу работали как ожидается, по умолчанию рабочая директория команды Doxygen будет текущей директорией источника (т.е. CMAKE_CURRENT_SOURCE_DIR). Это можно переопределить с помощью опции WORKING_DIRECTORY, чтобы изменить используемую директорию в качестве относительной базовой точки. Обратите также внимание, что поведение Doxygen по умолчанию заключается в удалении рабочей директории из относительных путей в сгенерированной документации (см. опцию конфигурации Doxygen STRIP_FROM_PATH опцию конфигурации Doxygen для получения подробной информации).

Если предоставлено, необязательное значение comment будет передано как COMMENT для команды add_custom_target(), используемой для создания пользовательской цели внутри.

Добавлена в версии 3.27: Если CONFIG_FILE задано, указанный файл с полным путем будет использоваться в качестве файла конфигурации doxygen.

Добавлена в версии 3.12: Если ALL установлено, цель будет добавлена к целевому заданию по умолчанию.

Добавлена в версии 3.16: Если USE_STAMP_FILE установлено, пользовательская команда, определенная этой функцией, создаст файл отметки с именем <targetName>.stamp в текущей двоичной директории всякий раз, когда doxygen перезапускается. При наличии этой опции все элементы в <filesOrDirs> должны быть файлами (т.е. без каталогов, символических ссылок или подстановочных знаков), и каждый из файлов должен существовать в момент вызова doxygen_add_docs(). Возникнет ошибка, если любой из перечисленных элементов отсутствует или не является файлом, когда задано USE_STAMP_FILE. Будет создана зависимость от каждого из файлов, так что doxygen будет перезапущен только в том случае, если один из файлов обновлен. Без опции USE_STAMP_FILE, doxygen всегда будет перезапущен, если цель <targetName> построена, независимо от того, изменились ли какие-либо элементы, перечисленные в <filesOrDirs>.

Содержимое сгенерированного файла Doxyfile можно настроить, задав переменные CMake до вызова doxygen_add_docs(). Любая переменная с именем в формате DOXYGEN_<tag> будет иметь свое значение, подставленное для соответствующей опции конфигурации <tag> в Doxyfile. Обратитесь к документации Doxygen за полным списком поддерживаемых опций конфигурации.

Некоторые значения Doxygen по умолчанию переопределяются, чтобы обеспечить более подходящее поведение для проекта CMake. Каждый из следующих пунктов будет явно установлен, если переменная еще не имеет значения до вызова doxygen_add_docs() (с некоторыми исключениями):

DOXYGEN_HAVE_DOT

Установлено в YES если компонент dot был запрошен и найден, 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 это задается в формате, распознаваемом IDE Visual Studio: $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

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

Устаревшие переменные результатов

Для совместимости с предыдущими версиями CMake, следующие переменные также определены, но они устарели и больше не должны использоваться:

DOXYGEN_EXECUTABLE

Путь к команде doxygen. Если проектам необходимо напрямую обратиться к исполняемому файлу doxygen, они должны использовать импортируемый целевой объект Doxygen::doxygen вместо этого.

DOXYGEN_DOT_FOUND

Истина, если исполняемый файл dot был найден.

DOXYGEN_DOT_EXECUTABLE

Путь к команде dot. Если проектам необходимо напрямую обратиться к исполняемому файлу dot, они должны использовать импортируемый целевой объект Doxygen::dot вместо этого.

DOXYGEN_DOT_PATH

Путь к каталогу, содержащему исполняемый файл dot, как сообщается в DOXYGEN_DOT_EXECUTABLE. Путь может содержать косые черты даже в Windows и не подходит для непосредственного подстановки в шаблон Doxyfile.in. Если вам необходимо это значение, получите свойство IMPORTED_LOCATION целевого объекта Doxygen::dot и используйте get_filename_component() для извлечения части пути, обозначающей каталог. Также вы можете рассмотреть использование file(TO_NATIVE_PATH) для подготовки пути к файлу конфигурации Doxygen.

Устаревшие переменные подсказок

DOXYGEN_SKIP_DOT

Эта переменная не оказывает никакого влияния на компонентную форму find_package. В режиме обратной совместимости (т.е. без списка компонентов) она предотвращает поиск модулем поиска утилиты Graphviz dot.