Doxygen is a documentation generation tool (see https://www.doxygen.nl). This module looks for Doxygen and some optional tools it supports:
dotGraphviz dot utility used to render various
graphs.
mscgenMessage Chart Generator utility used
by Doxygen's \msc and \mscfile commands.
diaDia the diagram editor used by Doxygen's
\diafile command.
Added in version 3.9: These tools are available as components in the find_package() command.
For example:
# Require dot, treat the other components as optional
find_package(Doxygen
REQUIRED dot
OPTIONAL_COMPONENTS mscgen dia)
The following variables are defined by this module:
True if the doxygen executable was found.
The version reported by doxygen --version.
Added in version 3.9.
The module defines IMPORTED targets for Doxygen and each component found.
These can be used as part of custom commands, etc. and should be preferred over
old-style (and now deprecated) variables like DOXYGEN_EXECUTABLE. The
following import targets are defined if their corresponding executable could be
found (the component import targets will only be defined if that component was
requested):
Doxygen::doxygen
Doxygen::dot
Doxygen::mscgen
Doxygen::dia
Added in version 3.9.
This function is intended as a convenience for adding a target for generating documentation with Doxygen. It aims to provide sensible defaults so that projects can generally just provide the input files and directories and that will be sufficient to give sensible results. The function supports the ability to customize the Doxygen configuration used to build the documentation.
doxygen_add_docs(targetName
[filesOrDirs...]
[ALL]
[USE_STAMP_FILE]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[CONFIG_FILE filename])
The function constructs a Doxyfile and defines a custom target that runs
Doxygen on that generated file. The listed files and directories are used as
the INPUT of the generated Doxyfile and they can contain wildcards.
Any files that are listed explicitly will also be added as SOURCES of the
custom target so they will show up in an IDE project's source list.
So that relative input paths work as expected, by default the working
directory of the Doxygen command will be the current source directory (i.e.
CMAKE_CURRENT_SOURCE_DIR). This can be overridden with the
WORKING_DIRECTORY option to change the directory used as the relative
base point. 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 Doxygen config option for details).
If provided, the optional comment will be passed as the COMMENT for
the add_custom_target() command used to create the custom target
internally.
Added in version 3.27: If CONFIG_FILE is set, the given file provided with full-path
will be used as doxygen configuration file
Added in version 3.12: If ALL is set, the target will be added to the default build target.
Added in version 3.16: If USE_STAMP_FILE is set, the custom command defined by this function will
create a stamp file with the name <targetName>.stamp in the current
binary directory whenever doxygen is re-run. With this option present, all
items in <filesOrDirs> must be files (i.e. no directories, symlinks or
wildcards) and each of the files must exist at the time
doxygen_add_docs() is called. An error will be raised if any of the
items listed is missing or is not a file when USE_STAMP_FILE is given.
A dependency will be created on each of the files so that doxygen will only
be re-run if one of the files is updated. Without the USE_STAMP_FILE
option, doxygen will always be re-run if the <targetName> target is built
regardless of whether anything listed in <filesOrDirs> has changed.
The contents of the generated Doxyfile can be customized by setting CMake
variables before calling doxygen_add_docs(). Any variable with a name of
the form DOXYGEN_<tag> will have its value substituted for the
corresponding <tag> configuration option in the Doxyfile. See the
Doxygen documentation for the
full list of supported configuration options.
Some of Doxygen's defaults are overridden to provide more appropriate
behavior for a CMake project. Each of the following will be explicitly set
unless the variable already has a value before doxygen_add_docs() is
called (with some exceptions noted):
Set to YES if the dot component was requested and it was found,
NO otherwise. Any existing value of DOXYGEN_HAVE_DOT is ignored.
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.
Set to NO by this module.
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.
Populated with the name of the current project (i.e.
PROJECT_NAME).
Populated with the version of the current project (i.e.
PROJECT_VERSION).
Populated with the description of the current project (i.e.
PROJECT_DESCRIPTION).
Projects should not set this variable. It will be populated with the set of
files and directories passed to doxygen_add_docs(), thereby providing
consistent behavior with the other built-in commands like
add_executable(), add_library() and
add_custom_target(). If a variable named DOXYGEN_INPUT is set
by the project, it will be ignored and a warning will be issued.
Set to YES by this module.
If the set of inputs includes directories, this variable will specify
patterns used to exclude files from them. The following patterns are added
by doxygen_add_docs() to ensure CMake-specific files and directories
are not included in the input. If the project sets
DOXYGEN_EXCLUDE_PATTERNS, those contents are merged with these
additional patterns rather than replacing them:
*/.git/*
*/.svn/*
*/.hg/*
*/CMakeFiles/*
*/_CPack_Packages/*
DartConfiguration.tcl
CMakeLists.txt
CMakeCache.txt
Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that if
the project provides its own value for this and it is a relative path, it
will be converted to an absolute path relative to the current binary
directory. 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 the doxygen commands.
To change any of these defaults or override any other Doxygen config option,
set relevant variables before calling doxygen_add_docs(). For example:
set(DOXYGEN_GENERATE_HTML NO) set(DOXYGEN_GENERATE_MAN YES) doxygen_add_docs( doxygen ${PROJECT_SOURCE_DIR} COMMENT "Generate man pages" )
A number of Doxygen config options accept lists of values, but Doxygen requires
them to be separated by whitespace. CMake variables hold lists as a string with
items separated by semi-colons, so a conversion needs to be performed. The
doxygen_add_docs() command specifically checks the following Doxygen config
options and will convert their associated CMake variable's contents into the
required form if set. CMake variables are named DOXYGEN_<name> for the
Doxygen settings specified here.
|
|
The following single value Doxygen options will be quoted automatically if they contain at least one space:
|
|
Added in version 3.11: There are situations where it may be undesirable for a particular config option
to be automatically quoted by doxygen_add_docs(), such as ALIASES which
may need to include its own embedded quoting. The DOXYGEN_VERBATIM_VARS
variable can be used to specify a list of Doxygen variables (including the
leading DOXYGEN_ prefix) which should not be quoted. The project is then
responsible for ensuring that those variables' values make sense when placed
directly in the Doxygen input file. In the case of list variables, list items
are still separated by spaces, it is only the automatic quoting that is
skipped. For example, the following allows doxygen_add_docs() to apply
quoting to DOXYGEN_PROJECT_BRIEF, but not each item in the
DOXYGEN_ALIASES list (bracket syntax can also
be used to make working with embedded quotes easier):
set(DOXYGEN_PROJECT_BRIEF "String with spaces")
set(DOXYGEN_ALIASES
[[somealias="@some_command param"]]
"anotherAlias=@foobar"
)
set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
The resultant Doxyfile will contain the following lines:
PROJECT_BRIEF = "String with spaces"
ALIASES = somealias="@some_command param" anotherAlias=@foobar
Deprecated since version 3.9.
For compatibility with previous versions of CMake, the following variables are also defined but they are deprecated and should no longer be used:
The path to the doxygen command. If projects need to refer to the
doxygen executable directly, they should use the Doxygen::doxygen
import target instead.
True if the dot executable was found.
The path to the dot command. If projects need to refer to the dot
executable directly, they should use the Doxygen::dot import target
instead.
The path to the directory containing the dot executable 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 you need this value, get the IMPORTED_LOCATION property of the
Doxygen::dot target and use get_filename_component() to extract
the directory part of that path. You may also want to consider using
file(TO_NATIVE_PATH) to prepare the path for a Doxygen
configuration file.
Deprecated since version 3.9.
This variable has no effect for the component form of find_package.
In backward compatibility mode (i.e. without components list) it prevents
the finder module from searching for Graphviz's dot utility.