CMake does not support documentation building by default. However, we can use add_custom_target to perform arbitrary operations, and this is the mechanism that we leveraged in the present recipe. The important point to note is that we need to make sure that the tools necessary to build the documentation (Doxygen and Perl in this particular case) are available on the system.

In addition, note that the UseDoxygenDoc.cmake custom module only does the following:

• Performs a search for the Doxygen and Perl executables
• Defines a function

The actual creation of the docs target is left to a later invocation of the add_doxygen_doc function. This is an explicit is better than implicit pattern, which we consider a good CMake practice: do not use module inclusion to perform macro-like (or function-like) actions.

We have implemented add_doxygen_doc by using a function, and not a macro, in order to limit the scope and possible side-effects of variable definitions. In this particular case, both a function and a macro would work (and would yield the same result), but we recommend preferring functions over macros unless variables in the parent scope need to be modified.