Doxygen per CMake
« | 06 Apr 2025 | »Doxygen ist im GATE Projekt ein “alter Hut”.
Das Programm ist im CI Docker
und Script integriert und wartet nur auf seinen Aufruf.
Aber …
Wäre es nicht besser alle Tools (und auch Doxygen) über CMake anzusteuern?
In der Entwicklung haben wir unterschiedliche Tools, die wir unterschiedlich
kombinieren und in Scripts unterschiedlich zusammenwürfeln.
Jetzt ist es aber oft ärgerlich, wenn man immer wieder mal aus der
IDE zur
Konsole wechseln muss, um wieder eines der Tools anzuwerfen.
VSCode bietet in seinem
CMake Plugin immer eine Übersicht über alle ausführbaren Targets.
Ein Klick auf ein solches baut es und ein anderer Klick im
Test-Fenster startet die Tests.
Idee: Doxygen wird per CMake als Utility ausgeführt
CMake bietet mit
add_custom_target()
eine einfache Möglichkeit jedes beliebige Programm als Target zu registrieren.
Beim “Bauen” des Targets wird das registrierte Programm mit einstellbaren
Parametern gestartet.
Ich habe meine CMakeLists.txt daher um folgende Zeilen erweitert:
1function(gate_add_doxygen_target) 2 find_package(Doxygen REQUIRED) 3 4 add_custom_target(util_doxygen_run 5 COMMAND ${DOXYGEN_EXECUTABLE} "${CMAKE_SOURCE_DIR}/Doxyfile" 6 WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} 7 COMMENT "Executing doxygen documentation generation" 8 ) 9endfunction() 10 11find_package(Doxygen QUIET) 12option(GATE_BUILD_DOXYGEN "Build doxygen docu" ${DOXYGEN_FOUND}) 13 14if(GATE_BUILD_DOXYGEN) 15 gate_add_doxygen_target() 16endif()
Wird das Program doxygen im System gefunden, wird die CMake Option
GATE_BUILD_DOXYGEN aktiviert und dann die Funktion zum Hinzufügen des
Targets aufgerufen. Über die Option kann man das dann auch manuell
aus/einschalten.
Da ein Doxyfile ohne schon im Projekt ist, fehlt nur die Aufruf von
doxygen mit der Datei als Parameter.
Und mit dem nächsten Configure Klick in der VSCode CMake UI, finde ich
schon das neue Target util_doxygen_run in meiner Liste.
Ab sofort kann ich also einfach per Klick die Doku bauen lassen und
im Browser parallel überprüfen.
Fazit
Oft sind es die kleinen Dinge, die viel bewirken.
Man kann doxygen natürlich weiter manuell starten, aber der einfache
Klick im VSCode Fenster spart Zeit.
Ganz besonders wenn ich immer wieder Änderungen mache und das Ergebnis sofort sehen will, öffne ich im Browser die HTML-Datei und brauche dann nur einen VSCode-Klick und einen F5-Refresh im Browser um die neu-generierte Doku gegenlesen zu können.