18

I found on the Web a sample cmake file and put it in the /doc subdirectory of my project, where the file myproject.doxgen is also located, containing Doxygen configuration.

I've tested that running doxygen.exe myproject.doxygen produces valid output. I only need to build this into the CMake process. So /doc/CMakeLists.txt is:

find_package(Doxygen)
option(BUILD_DOCUMENTATION "Create and install the HTML based API        
documentation (requires Doxygen)" ${DOXYGEN_FOUND})

if(BUILD_DOCUMENTATION)
    if(NOT DOXYGEN_FOUND)
         message(FATAL_ERROR "Doxygen is needed to build the documentation.")
    endif()

    set(doxyfile_in ${CMAKE_CURRENT_SOURCE_DIR}/../doc/myproject.doxygen)
    set(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/doxyfile)

    configure_file(${doxyfile_in} ${doxyfile} @ONLY)

    message("Doxygen build started.")

    add_custom_target(doc
                      COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile_in}
                      WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/doc
                      COMMENT "Generating API documentation with Doxygen"
                      VERBATIM)

    #    install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION     share/doc)
endif()

It doesn't work for me, it only copies the original config file into /build/my/project/doc/ and does nothing more.

What I want is to generate the doxygen documentation during my builds; ideally, only when building the Release configuration.

Angew is no longer proud of SO
  • 167,307
  • 17
  • 350
  • 455
amigo421
  • 2,429
  • 4
  • 26
  • 55
  • 1
    The CMake file you've shown creates a build target `doc` which generates the doxymentation - that means that running e.g. `make doc` (or equivalent) will generate it. Does that work for you? Or do you need something else? – Angew is no longer proud of SO Jan 19 '16 at 13:46
  • I'm using the project in QT Creator. and doesn't run something from commandline. in /build/myproject/ it works without additional commands. just via "build" from IDE – amigo421 Jan 19 '16 at 13:55
  • 2
    There has to be a "project/target/whatever the QtCreator terminology is" named `doc`. Building that will build your documentation. Note that because there is no `ALL` argument after the `doc` in the `add_custom_target` command, the `doc` target is *not* part of `make all` (or equivalent). – Angew is no longer proud of SO Jan 19 '16 at 13:58
  • thank you. it works for me - flag ALL added doc to building process. however want to understand how to include into Release configuration only. do you know how to configure this? – amigo421 Jan 19 '16 at 14:16

1 Answers1

21

The way the CMake file you've shown is set up, it creates a target called doc; building that target (such as running make doc) generates the doxymentation. The target is not part of make all (or equivalent); to make it such, add ALL into the custom target creation:

add_custom_target(
  doc ALL
  COMMAND #... everything else as before
)

If you want to limit this target to only build in a particular configuration (as you've mentioned in comments), you can use generator expressions:

add_custom_target(
  doc ALL
  COMMAND $<$<CONFIG:Release>:${DOXYGEN_EXECUTABLE} ${doxyfile_in}>
  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/doc
  COMMENT "Generating API documentation with Doxygen"
  VERBATIM
)

It might happen that some CMake generators do not cope well with an empty COMMAND. With this in mind, the following should be fail-safe:

add_custom_target(
  doc ALL
  COMMAND
    $<$<CONFIG:Release>:${DOXYGEN_EXECUTABLE} ${doxyfile_in}>
    $<$<NOT:$<CONFIG:Release>>:${CMAKE_COMMAND} -E echo "Only done in Release builds">
  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/doc
  COMMENT "Generating API documentation with Doxygen"
  VERBATIM
)
Angew is no longer proud of SO
  • 167,307
  • 17
  • 350
  • 455
  • 1
    last version produces an error: "[ 33%] Generating API documentation with Doxygen The filename, directory name, or volume label syntax is incorrect. jom: C:\dev\workspace\build\myproject\doc\CMakeFiles\doc.dir\build.make [doc\CMakeFiles\doc] Error 1". do you know what does this mean ? – amigo421 Jan 19 '16 at 15:10
  • @amigo421 Hm, it's possible some CMake generators don't like the empty `COMMAND`. I've added a safer option – Angew is no longer proud of SO Jan 19 '16 at 15:27
  • thank you for your patience. I'm just starting cmake learning but need to get project working. however last version also is not working for my cmake . let me show you errors (two ones for that version) – amigo421 Jan 19 '16 at 15:37
  • first one: CMake Warning (dev) in doc/CMakeLists.txt: Syntax Warning in cmake code at C:/dev/workspace/myproject/doc/CMakeLists.txt:19:90 Argument not separated from preceding token by whitespace. This warning is for project developers. Use -Wno-dev to suppress it. – amigo421 Jan 19 '16 at 15:38
  • second one (if "jom" unknown for you - this is similar to nmake utility): The syntax of the command is incorrect. jom: C:\dev\workspace\build\myproject\doc\CMakeFiles\doc.dir\build.make [doc\CMakeFiles\doc] Error 1 [100%] Built target myproject jom: C:\dev\workspace\build\myproject\CMakeFiles\Makefile2 [doc\CMakeFiles\doc.dir\all] Error 2 jom: C:\dev\workspace\build\myproject\Makefile [all] Error 2. I suppose second one is a the same like first one , just on project build stage – amigo421 Jan 19 '16 at 15:40
  • @amigo421 Which CMake version? (BTW, sorry, I will likely only be available again tomorrow. Please try to read on generator expressions in the link I provided to see if maybe I've made a typo, or your CMake is not recent enough to support the genexes I used.) – Angew is no longer proud of SO Jan 19 '16 at 15:45
  • version 3.4.1. for me, looks your expression valid for me, but I'll re-check this again – amigo421 Jan 19 '16 at 15:59
  • @amigo421 Hm, I've experimented with this some more and I'm leaning towards a bug in CMake. I'll create a reproducer and ping the CMake mailing list. – Angew is no longer proud of SO Jan 20 '16 at 13:39
  • Thanks for this nice script! Would you know how to update it in order to make it compatible with the new doxygen_add_docs syntax? https://stackoverflow.com/questions/34878276/build-doxygen-from-cmake-script It auto-generates a stamp-file, and I was wondering how to connect it / pass it to your script via "DEPENDS". – ferdymercury Sep 09 '21 at 15:11