Tip of the day: CMake and Doxygen

August 14, 2010

With Doxygen, we have at hand a solid and widely-known open-source solution for the generation of API documentation. However, it is quite inconvenient when one has to use yet another tool as part of the daily hacking. So today, I looked into how I can integrate the generation of API documentation with my CMake workflow. Because I found no easy how-to on the web, I’m putting up one now.

The base situation is like this: In your source tree is somewhere a Doxyfile, which you previously used to generate documentation by running doxygen in this directory. Rename this file to “Doxyfile.in” and change the line that looks like

INPUT = ../src/



(Of course, substitute “../src/” by what’s actually in there.) Now add the following to the CMakeLists.txt of this directory:

# add a target to generate API documentation with Doxygen
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
COMMENT "Generating API documentation with Doxygen" VERBATIM

After another CMake run, you can type “make doc” to have CMake run Doxygen. To keep the source tree clean in out-of-source builds, the documentation is generated in the corresponding build directory. If that is too well hidden for you, exchange “CMAKE_CURRENT_SOURCE_DIR” for “CMAKE_CURRENT_BINARY_DIR” in the line starting with “WORKING_DIRECTORY”. The documentation will then be generated in the source directory again.

Installing the generated documentation is left as an exercise to the reader.

Update: I forgot to add one thing. With the above code, the target will not be included in the “all” target. That is, it will not be generated when you type “make”. You have to say “make doc” explicitly. If you want to include it in “make”, add the word “ALL” after “add_custom_target(doc”.

About these ads

12 Responses to “Tip of the day: CMake and Doxygen”

  1. ddd Says:

    nice Tip, thanks

  2. deorbit Says:

    Thank you for the tip, nice!
    I also had to make the change:

    It was good to know how to build (make doc) and that ALL would integrate it to the whole build.


  3. berenger Says:

    Thanks, nice code.

  4. Anu Pakanati Says:

    Very useful– thanks!

  5. […] As well as building your source, CMake can also run Doxygen to generate documentation after a build. Here’s a sample that I use based on the example here: […]

  6. Schnouki Says:

    Exactly what I needed — thanks!

  7. Keith Says:

    Thank you for this awesome guide. Is there a way to make it execute last rather than at the beginning?

  8. selfsimilarseashell Says:

    Thanks, it worked great.
    Minor improvement: if you write ALL inside add_custom_target, it will be built by default rather than having to do make doc.

  9. Brice Rivé Says:

    Very nice. Thanks!

  10. Luis Perez Says:

    Thank you very much for the tip, it has worked very well for me.
    Just an addition: if you have more than one subdirectory under your project directory in which you want to build the documentation (for example, I had a srclib and a srcprog for a library and a program that uses it) you can add the suggested lines to both CMakelists.txt but you must use two different names for the custom targets, i.e. add_custom_target(doclib …) and add_custom_target(docprog …)

  11. Paul Colby Says:

    Thanks for this! :)

    Another little tip, the Doxyfile.in can also include:


    This will automatically enable doxygen’s use of dot, if available.

    DOXYGEN_DOT_FOUND gets set (to YES, in my case) by the find_pacakge(Doxygen) command.


  12. You da programmer. Thanks :)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


Get every new post delivered to your Inbox.