💪🏼 🚩 🤩 CMake et C ++ - frères pour toujours 👩🏿‍🍳 🐖 🃏

L'amitié pour toujours

Pendant le processus de développement, j'aime changer les compilateurs, les modes de construction, les versions des dépendances, effectuer une analyse statique, mesurer les performances, collecter la couverture, générer de la documentation, etc. Et j'aime vraiment CMake, car cela me permet de faire tout ce que je veux.

Beaucoup grondent CMake, et souvent à juste titre, mais si vous regardez, tout n'est pas si mauvais, et dernièrement c'est très bon , et la direction du développement est assez positive.

Dans cet article, je veux dire à quel point il est simple d'organiser une bibliothèque d'en-tête C ++ dans le système CMake pour obtenir les fonctionnalités suivantes:

Assemblée;
Tests de démarrage automatique;
Mesure de la couverture du code;
Installation;
Documentation automatique
Génération de sandbox en ligne;
Analyse statique

Quiconque comprend déjà les avantages et la s-make peut simplement télécharger le modèle de projet et commencer à l'utiliser.

Table des matières

Projet de l'intérieur

Structure du projet

. ├── CMakeLists.txt ├── README.en.md ├── README.md ├── doc │  ├── CMakeLists.txt │  └── Doxyfile.in ├── include │  └── mylib │  └── myfeature.hpp ├── online │  ├── CMakeLists.txt │  ├── mylib-example.cpp │  └── wandbox.py └── test ├── CMakeLists.txt ├── mylib │  └── myfeature.cpp └── test_main.cpp

Nous parlerons principalement de la façon d'organiser les scripts CMake, ils seront donc analysés en détail. Tout le monde peut voir le reste des fichiers directement sur la page du modèle de projet .

Fichier CMake principal (./CMakeLists.txt)

Informations sur le projet

Tout d'abord, vous devez demander la bonne version du système CMake. CMake évolue, les signatures d'équipe, les comportements dans différentes conditions changent. Pour que CMake comprenne immédiatement ce que nous attendons de lui, nous devons immédiatement fixer nos exigences pour lui.

 cmake_minimum_required(VERSION 3.13)

Nous désignons ensuite notre projet, son nom, sa version, les langues utilisées, etc. (voir project ).

Dans ce cas, nous CXX langage CXX (ce qui signifie C ++) afin que CMake ne soit pas contraint et ne recherche pas le compilateur de langage C (par défaut, deux langages sont inclus dans CMake: C et C ++).

 project(Mylib VERSION 1.0 LANGUAGES CXX)

Ici, vous pouvez immédiatement vérifier si notre projet est inclus dans un autre projet en tant que sous-projet. Cela aidera grandement à l'avenir.

 get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Options de projet

Nous proposons deux options.

La première option - MYLIB_TESTING - pour désactiver les tests unitaires. Cela peut être nécessaire si nous sommes sûrs que tout est en ordre avec les tests et que nous voulons, par exemple, uniquement installer ou conditionner notre projet. Ou notre projet est inclus en tant que sous-projet - dans ce cas, l'utilisateur de notre projet n'est pas intéressé par l'exécution de nos tests. Vous ne testez pas les dépendances que vous utilisez?

 option(MYLIB_TESTING "  " ON)

De plus, nous MYLIB_COVERAGE une option distincte MYLIB_COVERAGE pour mesurer la couverture du code avec des tests, mais cela nécessitera des outils supplémentaires, vous devrez donc l'activer explicitement.

 option(MYLIB_COVERAGE "    " OFF)

Options de compilation

Bien sûr, nous sommes des programmeurs plus sympas, nous voulons donc le niveau maximum de diagnostics de temps de compilation du compilateur. Pas une seule souris ne passera.

 add_compile_options( -Werror -Wall -Wextra -Wpedantic -Wcast-align -Wcast-qual -Wconversion -Wctor-dtor-privacy -Wenum-compare -Wfloat-equal -Wnon-virtual-dtor -Wold-style-cast -Woverloaded-virtual -Wredundant-decls -Wsign-conversion -Wsign-promo )

Nous désactiverons également les extensions pour se conformer pleinement à la norme de langage C ++. Par défaut, ils sont inclus dans CMake.

 if(NOT CMAKE_CXX_EXTENSIONS) set(CMAKE_CXX_EXTENSIONS OFF) endif()

Objectif principal

Notre bibliothèque se compose uniquement de fichiers d'en-tête, ce qui signifie que nous n'avons aucun épuisement sous forme de bibliothèques statiques ou dynamiques. D'un autre côté, pour utiliser notre bibliothèque à l'extérieur, vous devez l'installer, vous devez pouvoir la trouver dans le système et la connecter à votre projet, et en même temps ces mêmes en-têtes sont liés avec elle, ainsi que, peut-être, quelques autres propriétés.

Pour cela, nous créons une bibliothèque d'interfaces.

 add_library(mylib INTERFACE)

Liez les en-têtes à notre bibliothèque frontale.

L'utilisation moderne, à la mode et jeune de CMake implique que les en-têtes, les propriétés, etc. transmis dans un seul but. Ainsi, il suffit de dire target_link_libraries(target PRIVATE dependency) , et tous les en-têtes associés à la cible de dependency seront disponibles pour les sources appartenant à la cible target . Et aucun [target_]include_directories n'est requis. Cela sera démontré ci-dessous lors de l'analyse du script CMake pour les tests unitaires .

Il convient également de prêter attention aux -: $<...> .

Cette commande associe les en-têtes dont nous avons besoin à notre bibliothèque frontale, et si notre bibliothèque est connectée à une cible au sein de la même hiérarchie CMake, alors les en-têtes du répertoire ${CMAKE_CURRENT_SOURCE_DIR}/include y seront associés, et si la nôtre Étant donné que la bibliothèque est installée sur le système et connectée à un autre projet à l'aide de la find_package , les en-têtes du répertoire include relatifs au répertoire d'installation lui seront associés.

 target_include_directories(mylib INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:include> )

Définissez la norme de langue. Bien sûr, le tout dernier. Dans le même temps, nous incluons non seulement la norme, mais la distribuons également à ceux qui utiliseront notre bibliothèque. Cela est dû au fait que la propriété set a la catégorie INTERFACE (voir la commande target_compile_features ).

 target_compile_features(mylib INTERFACE cxx_std_17)

Nous créons un alias pour notre bibliothèque. De plus, pour la beauté, il sera dans un "espace de noms" spécial. Cela sera utile lorsque différents modules apparaissent dans notre bibliothèque, et nous allons les connecter indépendamment les uns des autres. Comme dans Boost, par exemple .

 add_library(Mylib::mylib ALIAS mylib)

L'installation

Installer nos en-têtes dans le système. Ici, tout est simple. Nous disons que le dossier avec tous les en-têtes doit être dans le répertoire include relatif à l'emplacement d'installation.

 install(DIRECTORY include/mylib DESTINATION include)

Ensuite, nous informons le système de construction que nous voulons pouvoir appeler find_package(Mylib) dans des projets tiers et obtenir la cible Mylib::mylib .

 install(TARGETS mylib EXPORT MylibConfig) install(EXPORT MylibConfig NAMESPACE Mylib:: DESTINATION share/Mylib/cmake)

Le sort suivant doit être compris comme suit. Lorsque nous appelons find_package(Mylib 1.2.3 REQUIRED) dans un projet tiers, et dans ce cas, la version réelle de la bibliothèque installée sera incompatible avec la version 1.2.3 , CMake générera automatiquement une erreur. Autrement dit, vous n'aurez pas besoin de suivre les versions manuellement.

 include(CMakePackageConfigHelpers) write_basic_package_version_file("${PROJECT_BINARY_DIR}/MylibConfigVersion.cmake" VERSION ${PROJECT_VERSION} COMPATIBILITY AnyNewerVersion ) install(FILES "${PROJECT_BINARY_DIR}/MylibConfigVersion.cmake" DESTINATION share/Mylib/cmake)

Les tests

Si les tests sont désactivés explicitement en utilisant l' option appropriée ou si notre projet est un sous-projet, c'est-à-dire connecté à un autre projet CMake à l'aide de la add_subdirectory , nous n'irons pas plus loin dans la hiérarchie et le script qui décrit les commandes pour générer et exécuter les tests ne démarre tout simplement pas .

 if(NOT MYLIB_TESTING) message(STATUS "  Mylib ") elseif(IS_SUBPROJECT) message(STATUS "Mylib     ") else() add_subdirectory(test) endif()

La documentation

La documentation ne sera pas non plus générée dans le cas d'un sous-projet.

 if(NOT IS_SUBPROJECT) add_subdirectory(doc) endif()

Sandbox en ligne

De même, le sous-projet n'aura pas non plus de bacs à sable en ligne.

 if(NOT IS_SUBPROJECT) add_subdirectory(online) endif()

Script pour les tests (test / CMakeLists.txt)

Test

Tout d'abord, nous trouvons le package avec le framework de test souhaité (remplacez-le par votre favori).

 find_package(doctest 2.3.3 REQUIRED)

Nous créons notre fichier exécutable avec des tests. Habituellement, j'ajoute uniquement le fichier dans lequel la fonction main sera directement au binaire exécutable.

 add_executable(mylib-unit-tests test_main.cpp)

Et les fichiers qui décrivent les tests eux-mêmes sont ajoutés ultérieurement. Mais ce n'est pas nécessaire.

 target_sources(mylib-unit-tests PRIVATE mylib/myfeature.cpp)

Nous connectons les dépendances. Veuillez noter que nous avons uniquement target_include_directories cibles CMake dont nous avions besoin à notre binaire et n'avons pas appelé la commande target_include_directories . Les en-têtes du framework de test et de notre Mylib::mylib , ainsi que les paramètres de build (dans notre cas, c'est le standard du langage C ++) ont exploré ces objectifs.

 target_link_libraries(mylib-unit-tests PRIVATE Mylib::mylib doctest::doctest )

Enfin, créez une cible fictive, dont le «assembly» équivaut à l'exécution de tests, et ajoutez cette cible à l'assembly par défaut (l'attribut ALL est responsable). Cela signifie que l'assembly par défaut initie le lancement des tests, c'est-à-dire que nous n'oublierons jamais de les exécuter.

 add_custom_target(check ALL COMMAND mylib-unit-tests)

Couverture

Ensuite, nous activons la mesure de la couverture du code, si l'option correspondante est spécifiée. Je n'entrerai pas dans les détails, car ils concernent plus l'outil de mesure de la couverture que CMake. Il est seulement important de noter que, sur la base des résultats, un objectif de coverage sera créé, avec lequel il est commode de commencer à mesurer la couverture.

 find_program(GCOVR_EXECUTABLE gcovr) if(MYLIB_COVERAGE AND GCOVR_EXECUTABLE) message(STATUS "    ") target_compile_options(mylib-unit-tests PRIVATE --coverage) target_link_libraries(mylib-unit-tests PRIVATE gcov) add_custom_target(coverage COMMAND ${GCOVR_EXECUTABLE} --root=${PROJECT_SOURCE_DIR}/include/ --object-directory=${CMAKE_CURRENT_BINARY_DIR} DEPENDS check ) elseif(MYLIB_COVERAGE AND NOT GCOVR_EXECUTABLE) set(MYLIB_COVERAGE OFF) message(WARNING "       gcovr") endif()

Script pour la documentation (doc / CMakeLists.txt)

Trouvé Doxygen .

 find_package(Doxygen)

Ensuite, nous vérifions si l'utilisateur a défini la variable de langue. Si oui, ne touchez pas, sinon, prenez le russe. Configurez ensuite les fichiers système Doxygen. Toutes les variables nécessaires, y compris la langue, y parviennent lors du processus de configuration (voir configure_file ).

Ensuite, nous créons la cible doc , qui commencera la génération de la documentation. Étant donné que la génération de documentation n'est pas le plus grand besoin dans le processus de développement, par défaut, l'objectif ne sera pas activé, il devra être démarré explicitement.

 if (Doxygen_FOUND) if (NOT MYLIB_DOXYGEN_LANGUAGE) set(MYLIB_DOXYGEN_LANGUAGE Russian) endif() message(STATUS "Doxygen documentation will be generated in ${MYLIB_DOXYGEN_LANGUAGE}") configure_file(Doxyfile.in Doxyfile) add_custom_target(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) endif ()

Script pour un sandbox en ligne (online / CMakeLists.txt)

Ici, nous trouvons le troisième Python et créons une cible wandbox qui génère une demande qui correspond à l'API du service Wandbox et l'envoie. En réponse, un lien vers le bac à sable fini vient.

 find_program(PYTHON3_EXECUTABLE python3) if(PYTHON3_EXECUTABLE) set(WANDBOX_URL "https://wandbox.org/api/compile.json") add_custom_target(wandbox COMMAND ${PYTHON3_EXECUTABLE} wandbox.py mylib-example.cpp "${PROJECT_SOURCE_DIR}" include | curl -H "Content-type: application/json" -d @- ${WANDBOX_URL} WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} DEPENDS mylib-unit-tests ) else() message(WARNING "  -    python 3- ") endif()

Projet extérieur

Considérez maintenant comment tout utiliser.

Assemblage

L'assemblage de ce projet, comme tout autre projet sur le système d'assemblage CMake, se compose de deux étapes:

Génération

 cmake -S // -B /// [ ...]

Si la commande ci-dessus n'a pas fonctionné en raison de l'ancienne version de CMake, essayez d'omettre -S :
 cmake // -B /// [ ...] 

En savoir plus sur les options .

Montage du projet

 cmake --build /// [--target target]

En savoir plus sur les objectifs d'assemblage .

Les options

MYLIB_COVERAGE

 cmake -S ... -B ... -DMYLIB_COVERAGE=ON [  ...]

Comprend un objectif de coverage , avec lequel vous pouvez commencer à mesurer la couverture de code avec des tests.

MYLIB_TESTING

 cmake -S ... -B ... -DMYLIB_TESTING=OFF [  ...]

Permet de désactiver l'assemblage de test unitaire et la cible de check . Par conséquent, la mesure de la couverture du code par les tests est désactivée (voir MYLIB_COVERAGE ).

De plus, le test est automatiquement désactivé si le projet est connecté à un autre projet en tant que sous-projet à l'aide de la add_subdirectory .

MYLIB_DOXYGEN_LANGUAGE

 cmake -S ... -B ... -DMYLIB_DOXYGEN_LANGUAGE=English [  ...]

Bascule le langage de doc généré par la cible doc vers celui spécifié. Pour une liste des langues disponibles, consultez le site Web de Doxygen .

Par défaut, le russe est activé.

Objectifs de l'Assemblée

Par défaut

 cmake --build path/to/build/directory cmake --build path/to/build/directory --target all

Si la cible n'est pas spécifiée (ce qui équivaut à l'objectif all ), collecte tout ce qui est possible et appelle également la cible de check .

tests unitaires mylib

 cmake --build path/to/build/directory --target mylib-unit-tests

Compile les tests unitaires. Activé par défaut.

vérifier

 cmake --build /// --target check

Exécute les tests unitaires collectés (collecte, si pas encore). Activé par défaut.

Voir aussi mylib-unit-tests .

couverture

 cmake --build /// --target coverage

Analyse les tests unitaires en cours d'exécution (s'exécute, si ce n'est pas encore) pour couvrir le code avec des tests utilisant le programme gcovr .

Le revêtement d'échappement ressemblera à ceci:

 ------------------------------------------------------------------------------ GCC Code Coverage Report Directory: /path/to/cmakecpptemplate/include/ ------------------------------------------------------------------------------ File Lines Exec Cover Missing ------------------------------------------------------------------------------ mylib/myfeature.hpp 2 2 100% ------------------------------------------------------------------------------ TOTAL 2 2 100% ------------------------------------------------------------------------------

La cible n'est disponible que lorsque MYLIB_COVERAGE .

Voir aussi check .

doc

 cmake --build /// --target doc

Démarre la génération de la documentation du code à l'aide du système Doxygen .

wandbox

 cmake --build /// --target wandbox

La réponse du service ressemble à ceci:

 { "permlink" : "QElvxuMzHgL9fqci", "status" : "0", "url" : "https://wandbox.org/permlink/QElvxuMzHgL9fqci" }

Pour ce faire, utilisez le service Wandbox . Je ne sais pas comment ils ont des serveurs en caoutchouc, mais je pense que cette opportunité ne doit pas être abusée.

Des exemples

Assemblage de projet en mode débogage avec mesure de couverture

 cmake -S // -B /// -DCMAKE_BUILD_TYPE=Debug -DMYLIB_COVERAGE=ON cmake --build /// --target coverage --parallel 16

Installation du projet sans assemblage ni test préliminaires

 cmake -S // -B /// -DMYLIB_TESTING=OFF -DCMAKE_INSTALL_PREFIX=/// cmake --build /// --target install

Construire en mode release par le compilateur spécifié

 cmake -S // -B /// -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-8 -DCMAKE_PREFIX_PATH=///// cmake --build /// --parallel 4

Génération de documentation en anglais

 cmake -S // -B /// -DCMAKE_BUILD_TYPE=Release -DMYLIB_DOXYGEN_LANGUAGE=English cmake --build /// --target doc

Les outils

CMake 3.13

En fait, CMake 3.13 n'est requis que pour exécuter certaines des commandes de la console décrites dans cette aide. Du point de vue syntaxique des scripts CMake, la version 3.8 est suffisante si la génération est appelée d'une autre manière.
Bibliothèque de tests Doctest

Les tests peuvent être désactivés (voir l' MYLIB_TESTING ).
Doxygen

Pour changer la langue dans laquelle la documentation sera générée, l'option MYLIB_DOXYGEN_LANGUAGE est MYLIB_DOXYGEN_LANGUAGE .
Interprète Python 3

Pour générer automatiquement des sandbox en ligne .

Analyse statique

Avec CMake et quelques bons outils, vous pouvez fournir une analyse statique avec un minimum de mouvements corporels.

Cppcheck

CMake a un support intégré pour l' outil d'analyse statique Cppcheck .

Pour ce faire, utilisez l'option CMAKE_CXX_CPPCHECK :

 cmake -S // -B /// -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_CPPCHECK="cppcheck;--enable=all;-I///include"

Après cela, l'analyse statique sera automatiquement lancée à chaque fois pendant la compilation et la recompilation des sources. Vous n'avez rien à faire de plus.

Clang

En utilisant le merveilleux outil de scan-build , vous pouvez également exécuter une analyse statique en deux temps:

 scan-build cmake -S // -B /// -DCMAKE_BUILD_TYPE=Debug scan-build cmake --build ///

Ici, contrairement au cas avec Cppcheck, vous devez exécuter l'assembly à chaque fois via scan-build .

Postface

CMake est un système très puissant et flexible qui vous permet d'implémenter des fonctionnalités pour tous les goûts et toutes les couleurs. Et, bien que la syntaxe laisse parfois à désirer, le diable n'est toujours pas aussi terrible qu'il est peint. Utilisez le système de construction CMake au profit de la société et de la santé.

→ Télécharger le modèle de projet

CMake et C ++ - frères pour toujours