FindDoxygen

Doxygen — это инструмент генерации документации (см. http://www.doxygen.org). Этот модуль ищет Doxygen и некоторые дополнительные инструменты, которые он поддерживает. Эти инструменты включены в качестве компонентов в команде find_package():

dot

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

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.

Модуль определяет IMPORTED целевые задания для Doxygen и каждого найденного компонента. Они могут использоваться в пользовательских командах и т. д. и предпочтительнее устаревших (и теперь устаревших) переменных, таких как DOXYGEN_EXECUTABLE. Следующие целевые задания импорта определяются, если соответствующий исполняемый файл был найден (целевые задания импорта компонента будут определены только в том случае, если этот компонент был запрошен):

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

Функции

doxygen_add_docs

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

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

Функция создает Doxyfile и определяет пользовательское целевое задание, которое запускает Doxygen для этого сгенерированного файла. Указанные файлы и каталоги используются в качестве INPUT сгенерированного Doxyfile и могут содержать подстановочные знаки. Любые файлы, которые явно указаны, также будут добавлены в качестве SOURCES пользовательского целевого задания, поэтому они появятся в списке исходных файлов проекта IDE.

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

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

Если ALL установлено, целевое задание будет добавлено в целевое задание по умолчанию.

Если 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 в требуемый вид, если она установлена.

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

В некоторых случаях может быть нежелательно, чтобы определённый параметр конфигурации автоматически заключался в кавычки 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

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

Для совместимости с предыдущими версиями 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.