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>...] [...])
Additional Doxygen supporting tools, can be specified as components with the
find_package() command:
find_package(Doxygen [COMPONENTS <components>...])
Supported components include:
doxygenAdded in version 3.9.
Finds the doxygen executable. This component is always automatically
implied, even if not requested.
dotAdded in version 3.9.
Finds the Graphviz dot utility, used for
rendering graphs and diagrams as part of the documentation.
mscgenAdded in version 3.9.
Finds the Message Chart Generator
utility used by Doxygen's \msc and \mscfile commands.
diaAdded in version 3.9.
Finds the Dia diagram editor used by
Doxygen's \diafile command.
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::doxygenAdded in version 3.9.
Imported executable target encapsulating the doxygen executable usage
requirements, available if Doxygen is found.
Doxygen::dotAdded in version 3.9.
Imported executable target encapsulating the dot executable usage
requirements, available if the above dot component is found.
Doxygen::mscgenAdded in version 3.9.
Imported executable target encapsulating the mscgen executable usage
requirements, available if the above mscgen component is found.
Doxygen::diaAdded 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.
This module defines the following variables:
Doxygen_FOUNDBoolean 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_VERSIONThe version of Doxygen found (as reported by doxygen --version).
This module provides the following command:
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.
ALLAdded 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_FILEAdded 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.txtfind_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_DOTSet to YES if the dot component was requested and found, NO
otherwise. Any existing value of DOXYGEN_HAVE_DOT is ignored.
DOXYGEN_DOT_MULTI_TARGETSSet 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_LATEXSet to NO by this module.
DOXYGEN_WARN_FORMATFor 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_NAMEPopulated with the name of the current project (i.e.
PROJECT_NAME).
DOXYGEN_PROJECT_NUMBERPopulated with the version of the current project (i.e.
PROJECT_VERSION).
DOXYGEN_PROJECT_BRIEFPopulated with the description of the current project (i.e.
PROJECT_DESCRIPTION).
DOXYGEN_INPUTThis 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_RECURSIVESet to YES by this module.
DOXYGEN_EXCLUDE_PATTERNSIf 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_DIRECTORYSet 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:
|
|
For example, to customize the Doxygen file patterns, a usual semicolon-separated list can be set in CMake:
CMakeLists.txtfind_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:
|
|
DOXYGEN_VERBATIM_VARSAdded 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.txtfind_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_docsPROJECT_BRIEF = "String with spaces"
ALIASES = somealias="@some_command param" anotherAlias=@foobar
For compatibility with previous versions of CMake, the following variables are also defined but they are deprecated and should no longer be used:
DOXYGEN_EXECUTABLEDeprecated 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_FOUNDDeprecated since version 3.9.
Boolean result variable indicating whether dot executable is found.
DOXYGEN_DOT_EXECUTABLEDeprecated 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_PATHDeprecated 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_DOTDeprecated 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.
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)
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.txtcmake_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;
}
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()
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.txtfind_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.inPROJECT_NAME = "Customized project name"
OUTPUT_DIRECTORY = "@CMAKE_CURRENT_BINARY_DIR@"
# ...