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