FindDoxygen¶

Finds Doxygen, a source code documentation generator, along with some optional supporting tools, and provides a command for integrating Doxygen-based documentation into CMake projects:

find_package(Doxygen [<version>] [COMPONENTS <components>...] [...])

Components¶

Additional Doxygen supporting tools, can be specified as components with the find_package() command:

find_package(Doxygen [COMPONENTS <components>...])

Supported components include:

doxygen: Added in version 3.9.

Finds the doxygen executable. This component is always automatically implied, even if not requested.
dot: Added in version 3.9.

Finds the Graphviz dot utility, used for rendering graphs and diagrams as part of the documentation.
mscgen: Added in version 3.9.

Finds the Message Chart Generator utility used by Doxygen's \msc and \mscfile commands.
dia: Added in version 3.9.

Finds the Dia diagram editor used by Doxygen's \diafile command.

Imported Targets¶

This module provides the following Imported Targets, each of which is defined if the corresponding component was requested and its associated executable was found:

Doxygen::doxygen: Added in version 3.9.

Imported executable target encapsulating the doxygen executable usage requirements, available if Doxygen is found.
Doxygen::dot: Added in version 3.9.

Imported executable target encapsulating the dot executable usage requirements, available if the above dot component is found.
Doxygen::mscgen: Added in version 3.9.

Imported executable target encapsulating the mscgen executable usage requirements, available if the above mscgen component is found.
Doxygen::dia: Added in version 3.9.

Imported executable target encapsulating the dia executable usage requirements, available if the above dia component is found.

These targets can be used in commands such as add_custom_command() and are preferred over the older, now-deprecated variables like DOXYGEN_EXECUTABLE.

Result Variables¶

This module defines the following variables:

Doxygen_FOUND: Added in version 3.3.

Boolean indicating whether the (requested version of) doxygen executable and all requested required components were found.
Doxygen_VERSION: Added in version 4.2.

The version of Doxygen found (as reported by doxygen --version).

Commands¶

This module provides the following command:

doxygen_add_docs¶

Added in version 3.9.

Adds a custom target for generating documentation with Doxygen during the build phase:

doxygen_add_docs(
  <target-name>
  [<files-or-dirs>...]
  [ALL]
  [USE_STAMP_FILE]
  [WORKING_DIRECTORY <dir>]
  [COMMENT <comment>]
  [CONFIG_FILE <file>]
)

By default, this convenience command also generates a configuration file named Doxyfile.<target-name> in the current binary directory at CMake configuration phase. It provides sensible defaults, so most projects only need to specify input files or directories. Additional behavior and configuration can be customized using variables described in the following sections.

The arguments are:

<target-name>

The name of the target to be created for generating documentation with Doxygen.

<files-or-dirs>...

One or more paths (files or directories) that serve as input sources for documentation.

These are passed to the INPUT Doxygen configuration tag in the generated Doxyfile.<target-name>. Files listed here are also added as SOURCES argument of the underlying add_custom_target() command so they appear in IDE project's source list.

When using the USE_STAMP_FILE option, only files (not directories, symlinks, or wildcards) are allowed, and each must exist when this command is called.

ALL

Added in version 3.12.

Adds the created documentation target to the default build target so that it runs automatically as part of the build phase.

USE_STAMP_FILE

Added in version 3.16.

Enables use of a stamp file to avoid regenerating documentation unless source files have changed.

Stamp file named <target-name>.stamp is created in the current binary directory by an underlying custom command.

With this option present, all entries in <files-or-dirs> must be existing files (i.e. no directories, symlinks or wildcards) when this command is called. An error is raised if any listed path is invalid.

Without this option, CMake will re-run Doxygen every time the <target-name> target is built, regardless of whether any input source file listed in <files-or-dirs> has changed.

WORKING_DIRECTORY <dir>

By default, the Doxygen working directory is the current source directory (CMAKE_CURRENT_SOURCE_DIR). This aligns with using relative input paths.

Use this option, to change and override the directory where Doxygen is being run. The absolute path <dir> will then be used as the base point for relative paths.

Note also that Doxygen's default behavior is to strip the working directory from relative paths in the generated documentation. See the STRIP_FROM_PATH config tag in the Doxygen manual for more details.

COMMENT <comment>

If provided, the <comment> string will be passed as the COMMENT argument to the underlying add_custom_target() command used to create the custom target internally. This appears in the build system output, when the target is built.

CONFIG_FILE <file>

Added in version 3.27.

If specified, the given file provided with full-path will be used as Doxygen configuration file instead of the default Doxyfile.<target-name>.

Variables for customizing Doxygen configuration

The doxygen_add_docs() command generates a Doxygen configuration file containing configuration tags. For example:

Doxygen.<target-name>¶

DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = DoxygenExample
PROJECT_NUMBER         = 1.2.3
PROJECT_BRIEF          = "Example project using Doxygen"
PROJECT_LOGO           =
OUTPUT_DIRECTORY       = /home/user/doxygen-example/build
GENERATE_HTML          = YES
GENERATE_MAN           = NO
# ...

In CMake, these tags can be modified by setting input variables in form of DOXYGEN_<tag>, where <tag> is one of the configuration tags listed in the Doxygen manual.

For example, to modify the GENERATE_HTML and GENERATE_MAN configuration tags, the following variables can be set before calling doxygen_add_docs():

CMakeLists.txt¶

find_package(Doxygen)

if(Doxygen_FOUND)
  set(DOXYGEN_GENERATE_HTML NO)
  set(DOXYGEN_GENERATE_MAN YES)

  doxygen_add_docs(project_docs ${PROJECT_SOURCE_DIR})
endif()

Default configuration

By default, doxygen_add_docs() overrides several of Doxygen's settings to better suit typical CMake projects. Each of the following variables is explicitly set unless already defined prior to calling doxygen_add_docs(), with a few exceptions noted below:

DOXYGEN_HAVE_DOT

Set to YES if the dot component was requested and found, NO otherwise. Any existing value of DOXYGEN_HAVE_DOT is ignored.

DOXYGEN_DOT_MULTI_TARGETS

Set to YES by this module (note that this requires a dot version newer than 1.8.10). This option is only meaningful if DOXYGEN_HAVE_DOT is also set to YES.

DOXYGEN_GENERATE_LATEX

Set to NO by this module.

DOXYGEN_WARN_FORMAT

For Visual Studio based generators, this is set to the form recognized by the Visual Studio IDE: $file($line) : $text. For all other generators, Doxygen's default value is not overridden.

DOXYGEN_PROJECT_NAME

Populated with the name of the current project (i.e. PROJECT_NAME).

DOXYGEN_PROJECT_NUMBER

Populated with the version of the current project (i.e. PROJECT_VERSION).

DOXYGEN_PROJECT_BRIEF

Populated with the description of the current project (i.e. PROJECT_DESCRIPTION).

DOXYGEN_INPUT

This variable is automatically populated with the list of files and directories passed to doxygen_add_docs(). For consistent behavior with other built-in commands like add_executable(), add_library(), and add_custom_target(), projects should not set this variable manually. If a variable named DOXYGEN_INPUT is set by the project, it will be ignored and a warning will be issued.

DOXYGEN_RECURSIVE

Set to YES by this module.

DOXYGEN_EXCLUDE_PATTERNS

If the <files-or-dirs> argument of doxygen_add_docs() contains directories, this variable will specify patterns used to exclude files from them. The following patterns are added by default to ensure CMake-specific files and directories are not included in the input. If the project sets this variable, those contents are merged with these additional patterns rather than replacing them:

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

DOXYGEN_OUTPUT_DIRECTORY

Set to CMAKE_CURRENT_BINARY_DIR by this module. If the project provides its own value for this and it is a relative path, it will be interpreted relative to the current binary directory (CMAKE_CURRENT_BINARY_DIR). This is necessary because Doxygen will normally be run from a directory within the source tree so that relative source paths work as expected. If this directory does not exist, it will be recursively created prior to executing Doxygen.

Lists

A number of Doxygen config tags accept lists of values, and Doxygen requires them to be separated by whitespace, while in CMake a list is a string with items separated by semicolons.

The doxygen_add_docs() specifically checks for the following Doxygen config tags and converts their associated CMake DOXYGEN_<tag> variable values into the Doxygen-formatted lists if set:

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

For example, to customize the Doxygen file patterns, a usual semicolon-separated list can be set in CMake:

CMakeLists.txt¶

find_package(Doxygen)

if(Doxygen_FOUND)
  set(DOXYGEN_FILE_PATTERNS *.c *.cxx *.h *.hxx)
  doxygen_add_docs(example_docs ${CMAKE_CURRENT_SOURCE_DIR} ALL)
endif()

Which will produce a Doxygen list of patterns separated by spaces in the generated configuration file:

Doxyfile.<target-name>¶

# ...
FILE_PATTERNS          = *.c *.cxx *.h *.hxx

Automatic quoting

If a Doxygen single-value tag contains spaces, their values must be surrounded by double quotes ("..."). doxygen_add_docs() automatically quotes values of the following Doxygen tags when generating the Doxyfile, if they contain at least one space:

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_VERBATIM_VARS

Added in version 3.11.

A CMake input variable used by doxygen_add_docs() to specify a list of Doxygen input variables (including their leading DOXYGEN_ prefix) whose values should be passed to the generated Doxyfile configuration without automatic quoting.

When using this variable, the project is then responsible for ensuring that those variables' values make sense when placed directly in the generated Doxyfile configuration. For list variables, items are still separated by spaces in the output, but no quoting is applied to the individual items.

For certain Doxygen tags, such as ALIASES, automatic quoting done by doxygen_add_docs() may interfere with correct syntax (e.g., embedded quotes).

For example, the following will quote DOXYGEN_PROJECT_BRIEF, but skip each item in the DOXYGEN_ALIASES list (bracket syntax is used to make working with embedded quotes easier):

CMakeLists.txt¶

find_package(Doxygen)

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

  add_doxygen_docs(project_docs ${PROJECT_SOURCE_DIR})
endif()

The resultant Doxyfile configuration will contain the following lines:

Doxyfile.project_docs¶

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

Deprecated Variables¶

For compatibility with previous versions of CMake, the following variables are also defined but they are deprecated and should no longer be used:

DOXYGEN_FOUND: Deprecated since version 4.2: Use Doxygen_FOUND.

Boolean indicating whether the (requested version of) doxygen executable and all requested required components were found. It has a boolean value of YES or NO.
DOXYGEN_EXECUTABLE: Deprecated since version 3.9: Use Doxygen::doxygen imported target instead of referring to the doxygen executable directly.

Cache variable containing the path to the doxygen command.
DOXYGEN_DOT_FOUND: Deprecated since version 3.9: Use Doxygen_dot_FOUND.

Boolean result variable indicating whether dot executable was found.
DOXYGEN_DOT_EXECUTABLE: Deprecated since version 3.9: Use Doxygen::dot imported target instead of referring to the dot executable directly.

Cache variable containing the path to the dot command-line executable.
DOXYGEN_DOT_PATH: Deprecated since version 3.9.

Result variable containing the path to the directory where the dot executable is located as reported in DOXYGEN_DOT_EXECUTABLE. The path may have forward slashes even on Windows and is not suitable for direct substitution into a Doxyfile.in template. If this value is needed, get the IMPORTED_LOCATION property of the Doxygen::dot target and use get_filename_component() to extract the directory part of that path. Consider also using file(TO_NATIVE_PATH) to prepare the path for a Doxygen configuration file.
DOXYGEN_SKIP_DOT: Deprecated since version 3.9.

This hint variable has no effect when specifying components in find_package(Doxygen COMPONENTS ...). In backward-compatibility mode (i.e. without specifying components) it prevents this find module from searching for Graphviz's dot utility.
DOXYGEN_VERSION: Deprecated since version 4.2: Superseded by the Doxygen_VERSION.

The version of Doxygen found.

Examples¶

Examples: Finding Doxygen¶

Finding Doxygen:

find_package(Doxygen)

Or, finding Doxygen and specifying a minimum required version:

find_package(Doxygen 1.9)

Or, finding Doxygen and making it required (if not found, processing stops with an error message):

find_package(Doxygen REQUIRED)

Or, finding Doxygen as required and specifying dot tool as required component and mscgen and dia tools as optional components:

find_package(Doxygen REQUIRED COMPONENTS dot OPTIONAL_COMPONENTS mscgen dia)

Example: Using Doxygen in CMake¶

The following example demonstrates how to find Doxygen and create documentation from source files at build phase. Once project is built, generated documentation files will be located in the html directory inside the project binary directory:

CMakeLists.txt¶

cmake_minimum_required(VERSION 3.24)
project(
  DoxygenExample
  DESCRIPTION "Example project using Doxygen"
  VERSION 1.2.3
)

add_executable(example example.c)

find_package(Doxygen)

if(Doxygen_FOUND)
  doxygen_add_docs(project_docs example.c ALL USE_STAMP_FILE)
endif()

example.c¶

/**
 * @file example.c
 * @brief A simple example to demonstrate Doxygen.
 */

#include <stdio.h>

/**
 * @brief Calculates the sum of two integers.
 *
 * @param a First integer.
 * @param b Second integer.
 * @return Sum of a and b.
 *
 * @par Example
 * @code
 * int result = sum(3, 4);
 * printf("%d\n", result); // Outputs: 7
 * @endcode
 */
int sum(int a, int b) { return a + b; }

/**
 * @brief Main function.
 *
 * @return 0 on success.
 */
int main(void)
{
  int result = sum(5, 7);
  printf("Result: %d\n", result);
  return 0;
}

Example: Configuring Doxygen With Variables¶

In the following example, Doxygen configuration is customized using CMake variables. The configuration sets file patterns when using a directory as the source input (CMAKE_CURRENT_SOURCE_DIR), enables a theme toggle for switching between light and dark modes, suppresses Doxygen's standard output during the build phase, specifies a Markdown file as the main page, and disables warnings about undocumented code:

find_package(Doxygen)

if(Doxygen_FOUND)
  set(DOXYGEN_FILE_PATTERNS *.c *.cxx *.md)
  set(DOXYGEN_HTML_COLORSTYLE "TOGGLE")
  set(DOXYGEN_QUIET YES)
  set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${CMAKE_CURRENT_SOURCE_DIR}/README.md")
  set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)

  doxygen_add_docs(example_docs ${CMAKE_CURRENT_SOURCE_DIR} ALL)
endif()

Example: Custom Configuration File¶

In the following example, a custom Doxyfile configuration file is created in the current binary directory (CMAKE_CURRENT_BINARY_DIR) prior to calling the doxygen_add_docs(). This allows project-specific configuration tags to be customized as needed:

CMakeLists.txt¶

find_package(Doxygen)

if(Doxygen_FOUND)
  configure_file(Doxyfile.in Doxyfile)

  doxygen_add_docs(
    example_docs
    foo.c bar.c
    ALL
    USE_STAMP_FILE
    COMMENT "Generating project documentation with custom Doxyfile"
    CONFIG_FILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
  )
endif()

Doxyfile.in¶

PROJECT_NAME           = "Customized project name"
OUTPUT_DIRECTORY       = "@CMAKE_CURRENT_BINARY_DIR@"
# ...

FindDoxygen¶

Components¶

Imported Targets¶

Result Variables¶

Commands¶

Deprecated Variables¶

Examples¶

Examples: Finding Doxygen¶

Example: Using Doxygen in CMake¶

Example: Configuring Doxygen With Variables¶

Example: Custom Configuration File¶

Table of Contents

Previous topic

Next topic

This Page