Le fichier CMakeLists.txt

2.1.4.1 : Le fichier CMakeLists.txt

Le fichier CMakeLists.txt du dossier doc va nous permettre de générer notre documentation avec un simple make doc :

Commençons par créer le dossier où sera générée la documentation :

1	file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html)

Doxygen créé toujours un dossier html pour la documentation html afin de ne pas la mélanger avec une éventuelle décumentation pdf, ou la documentation man (de la commande man) qui est généré dans un dossier man.

Ensuite, nous récupérons tous les fichiers qui peuvent contenir de la documentation : cpp, h et dox (le format de Doxygen) :

1 2	file(GLOB_RECURSE allDocFiles ${CMAKE_SOURCE_DIR}/.cpp .h *.dox) string(REGEX REPLACE "${CMAKE_BINARY_DIR}[^;]+;?" "" allDocFiles "${allDocFiles}")

Définissons le logo et le dossier générique de la documentation :

1 2	set(PROJECT_LOGO ${CMAKE_CURRENT_SOURCE_DIR}/logo.png) set(OUTPUT_DOC_DIR ${CMAKE_CURRENT_BINARY_DIR}/)

Nous appelons la commande configure_file qui va nous générer la configuration pour notre projet :

1	configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.cmake ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)

L'option @ONLY permet de dire à CMake de ne remplacer que les variables définies entre @ :

Définissons le nom d'une cible pour créer la documentation spécifique du projet :

1	set(targetName "doc_${PROGRAM_NAME}")

Nous aurions très bien pu définir une cible doc tout de suite, mais le faire cette façon permet d'éviter les conflits si vous mélangez plusieurs projets entre eux.

Maintenant, ajoutons une commande (que nous pourrons appeler avec make doc_TestGitlabCI) :

1	add_custom_command(

Pour pouvoir appeler une commande, il faut tout d'abord définir ce qu'elle produit :

1 2	OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc.txt OUTPUT ${targetName}

Un petit commentaire pour dire ce que l'on est en train de faire :

1	COMMENT "doxygen documentation generation for project ${PROGRAM_NAME}"

L'appel de Doxygen (nous partons du principe qu'il est installé mais il faudrait tester sa présence pour être vraiment propre) :

1	COMMAND doxygen ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile

Les dépendences seront sur tous les fichiers scannés du début. Comme ceci, dès qu'il y aura une modification, la documentation sera regénérée automatiquement :

1	DEPENDS ${allDocFiles}

Le dossier dans lequel s'exécutera la commande :

1	WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}

Puis, on termine la définission de la commande :

Nous associons la commande précédente à la cible qui permet de créer le fichier doc.txt :

1	add_custom_target(${targetName} DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doc.txt)

Ici, nous créons une cible doc si elle n'existe pas déja. Cela permet d'éviter les conflits évoqués précédemment :

1
2
3

if(NOT TARGET doc)
	add_custom_target(doc)
endif()

Ensuite, nous ajoutons une dépendence à la cible doc. Comme cela nous retombons sur la convention qui implique de générer la documentation d'un projet avec make doc :

1	add_dependencies(doc ${targetName})

Enfin, nous indiquons où installer la documentation générée :

1	install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html DESTINATION share/${PROGRAM_NAME}/doc)

Ici, nous le faisons qu'avec le html, mais il faut bien sur installer le man si vous le gérérez aussi.

Le fichier CMakeLists.txt complet :

file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html)

file(GLOB_RECURSE allDocFiles ${CMAKE_SOURCE_DIR}/*.cpp *.h *.dox)
string(REGEX REPLACE "${CMAKE_BINARY_DIR}[^;]+;?" "" allDocFiles "${allDocFiles}")

set(PROJECT_LOGO ${CMAKE_CURRENT_SOURCE_DIR}/logo.png)
set(OUTPUT_DOC_DIR ${CMAKE_CURRENT_BINARY_DIR}/)

configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.cmake ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)

set(targetName "doc_${PROGRAM_NAME}")

add_custom_command(

	OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc.txt
	OUTPUT ${targetName}

	COMMENT "doxygen documentation generation for project ${PROGRAM_NAME}"

	COMMAND doxygen ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile

	DEPENDS ${allDocFiles}

	WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}

)

add_custom_target(${targetName} DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doc.txt)

if(NOT TARGET doc)
	add_custom_target(doc)
endif()

add_dependencies(doc ${targetName})

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

Vous pouvez le télécharger ici.