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/

into

INPUT = @CMAKE_CURRENT_SOURCE_DIR@/../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
find_package(Doxygen)
if(DOXYGEN_FOUND)
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
add_custom_target(doc
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen" VERBATIM
)
endif(DOXYGEN_FOUND)

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

8 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:
    OUTPUT_DIRECTORY=@CMAKE_CURRENT_BINARY_DIR@

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

    Thanks!

  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.


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

Follow

Get every new post delivered to your Inbox.