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

Boolean indicating whether (the requested version of) doxygen executable and all requested required components are found. For backward compatibility, the DOXYGEN_FOUND variable is also set, except it has boolean value of YES or NO.

DOXYGEN_VERSION

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_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.

Boolean result variable indicating whether dot executable is 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.

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_doxs(). 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_doxs(
    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@"
# ...