🥇CMake en C++ zijn voor altijd broers

Tijdens de ontwikkeling houd ik ervan om compilers te veranderen, modi te bouwen, afhankelijkheidsversies te maken, statische analyses uit te voeren, prestaties te meten, dekking te verzamelen, documentatie te genereren, enz. En ik hou echt van CMake omdat ik hiermee alles kan doen wat ik wil.

Veel mensen bekritiseren CMake, en vaak terecht, maar als je ernaar kijkt, is niet alles zo slecht, en recentelijk helemaal niet slecht, en de richting van de ontwikkeling is vrij positief.

In deze notitie wil ik je vertellen hoe je eenvoudigweg een headerbibliotheek in C++ in het CMake-systeem kunt organiseren om de volgende functionaliteit te krijgen:

Montage;
Autorun-tests;
Meting van codedekking;
Installatie;
Automatische documentatie;
Online sandbox-generatie;
Statische analyse.

Iedereen die de voordelen en C-make al begrijpt, kan dat gewoon doen projectsjabloon downloaden en begin het te gebruiken.

Projecteer van binnenuit

Projectstructuur

.
├── 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

We zullen vooral praten over het organiseren van CMake-scripts, dus ze zullen in detail worden besproken. Iedereen kan de rest van de bestanden direct bekijken op de sjabloonprojectpagina.

Hoofd CMake-bestand (./CMakeLists.txt)

Project informatie

Allereerst moet u de vereiste versie van het CMake-systeem aanvragen. CMake evolueert, commandohandtekeningen en gedrag onder verschillende omstandigheden veranderen. Om ervoor te zorgen dat CMake onmiddellijk begrijpt wat we ervan willen, moeten we onmiddellijk onze vereisten ervoor vastleggen.

cmake_minimum_required(VERSION 3.13)

Vervolgens zullen we ons project, de naam, de versie, de gebruikte talen, enz. aanduiden (zie. команду project).

In dit geval geven we de taal aan CXX (en dit betekent C++), zodat CMake niet hoeft te zoeken naar een C-taalcompiler (standaard bevat CMake twee talen: C en C++).

project(Mylib VERSION 1.0 LANGUAGES CXX)

Hier kunt u direct controleren of ons project als deelproject is opgenomen in een ander project. Dit zal in de toekomst veel helpen.

get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Projectopties

We zullen twee opties bieden.

De eerste optie is MYLIB_TESTING — om unit-tests uit te schakelen. Dit kan nodig zijn als we er zeker van zijn dat alles in orde is met de tests, maar we bijvoorbeeld alleen ons project willen installeren of verpakken. Of ons project is opgenomen als subproject - in dit geval is de gebruiker van ons project niet geïnteresseerd in het uitvoeren van onze tests. Je test de afhankelijkheden die je gebruikt toch niet?

option(MYLIB_TESTING "Включить модульное тестирование" ON)

Daarnaast maken wij een aparte optie MYLIB_COVERAGE voor het meten van de codedekking door middel van tests, maar hiervoor zijn extra tools nodig, dus het moet expliciet worden ingeschakeld.

option(MYLIB_COVERAGE "Включить измерение покрытия кода тестами" OFF)

Compilatie-opties

Natuurlijk zijn we coole plus-programmeurs, dus we willen het maximale niveau van diagnostiek tijdens het compileren van de compiler. Geen enkele muis zal er doorheen glippen.

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
)

We zullen ook extensies uitschakelen om volledig te voldoen aan de C++-taalstandaard. Ze zijn standaard ingeschakeld in CMake.

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

Het belangrijkste doel

Onze bibliotheek bestaat alleen uit headerbestanden, wat betekent dat we geen uitputting hebben in de vorm van statische of dynamische bibliotheken. Aan de andere kant, om onze bibliotheek extern te kunnen gebruiken, moet deze geïnstalleerd zijn, detecteerbaar zijn in het systeem en verbonden zijn met uw project, en tegelijkertijd moeten dezelfde headers, en mogelijk enkele extra, zijn aan de eigenschappen verbonden.

Voor dit doel creëren we een interfacebibliotheek.

add_library(mylib INTERFACE)

We binden headers aan onze interfacebibliotheek.

Modern, modieus gebruik door jongeren van CMake impliceert dat headers, eigenschappen, enz. verzonden via één enkel doel. Het volstaat dus te zeggen target_link_libraries(target PRIVATE dependency)en alle headers die aan het doel zijn gekoppeld dependency, zal beschikbaar zijn voor bronnen die tot het doelwit behoren target. En je hebt er geen nodig [target_]include_directories. Dit zal hieronder in de analyse worden aangetoond CMake-script voor unit-tests.

Het is ook de moeite waard om aandacht te besteden aan de zogenaamde. выражения-генераторы: $<...>.

Deze opdracht koppelt de headers die we nodig hebben aan onze interfacebibliotheek, en als onze bibliotheek is verbonden met een doel binnen dezelfde CMake-hiërarchie, worden de headers uit de map eraan gekoppeld ${CMAKE_CURRENT_SOURCE_DIR}/include, en of onze bibliotheek op het systeem is geïnstalleerd en met een ander project is verbonden met behulp van de opdracht find_package, dan worden er headers uit de map aan gekoppeld include relatief ten opzichte van de installatiemap.

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

Laten we een taalstandaard instellen. Uiteraard de allerlaatste. Tegelijkertijd nemen we niet alleen de standaard op, maar breiden we deze ook uit naar degenen die onze bibliotheek gaan gebruiken. Dit wordt bereikt doordat de set-eigenschap een categorie heeft INTERFACE (Zie. target_compile_features-opdracht).

target_compile_features(mylib INTERFACE cxx_std_17)

Laten we een alias maken voor onze bibliotheek. Bovendien zal het voor schoonheid in een speciale "naamruimte" staan. Dit zal handig zijn als er verschillende modules in onze bibliotheek verschijnen en we ze onafhankelijk van elkaar gaan verbinden. Zoals bijvoorbeeld in Busta.

add_library(Mylib::mylib ALIAS mylib)

installatie

Onze headers in het systeem installeren. Alles is hier eenvoudig. We zeggen dat de map met alle headers in de map moet komen include ten opzichte van de installatielocatie.

install(DIRECTORY include/mylib DESTINATION include)

Vervolgens informeren we het bouwsysteem dat we de opdracht willen kunnen aanroepen in projecten van derden find_package(Mylib) en een doelpunt krijgen Mylib::mylib.

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

De volgende spreuk moet op deze manier worden begrepen. In een project van derden roepen we de opdracht aan find_package(Mylib 1.2.3 REQUIRED), en de echte versie van de geïnstalleerde bibliotheek zal incompatibel zijn met de versie 1.2.3CMake genereert automatisch een fout. Dat wil zeggen dat u versies niet handmatig hoeft bij te houden.

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)

Testen

Als tests expliciet worden uitgeschakeld met behulp van overeenkomstige optie of ons project is een subproject, dat wil zeggen dat het met behulp van de opdracht is verbonden met een ander CMake-project add_subdirectory, we gaan niet verder in de hiërarchie, en het script, dat de opdrachten beschrijft voor het genereren en uitvoeren van tests, werkt eenvoudigweg niet.

if(NOT MYLIB_TESTING)
    message(STATUS "Тестирование проекта Mylib выключено")
elseif(IS_SUBPROJECT)
    message(STATUS "Mylib не тестируется в режиме подмодуля")
else()
    add_subdirectory(test)
endif()

Документация

Ook bij een deelproject wordt er geen documentatie gegenereerd.

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

Online zandbak

Op dezelfde manier zal het deelproject ook geen online sandbox hebben.

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

Testscript (test/CMakeLists.txt)

Testen

Allereerst vinden we een pakket met het vereiste testframework (vervangen door uw favoriete).

find_package(doctest 2.3.3 REQUIRED)

Laten we ons uitvoerbare bestand met tests maken. Meestal voeg ik rechtstreeks aan het uitvoerbare binaire bestand alleen het bestand toe dat de functie zal bevatten main.

add_executable(mylib-unit-tests test_main.cpp)

En ik voeg bestanden toe waarin de tests zelf later worden beschreven. Maar dat hoef je niet te doen.

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

Wij verbinden afhankelijkheden. Houd er rekening mee dat we alleen de CMake-doelen die we nodig hadden aan ons binaire bestand hebben gekoppeld en de opdracht niet hebben aangeroepen target_include_directories. Titels uit het testframework en uit het onze Mylib::mylib, evenals build-parameters (in ons geval is dit de C++-taalstandaard) kwamen samen met deze doelen tot stand.

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

Ten slotte maken we een dummydoel, waarvan de “build” gelijk is aan het uitvoeren van tests, en voegen we dit doel toe aan de standaardbuild (het attribuut is verantwoordelijk voor deze ALL). Dit betekent dat de standaardbuild ervoor zorgt dat de tests worden uitgevoerd, wat betekent dat we nooit zullen vergeten ze uit te voeren.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Покрытие

Vervolgens schakelen we het meten van de codedekking in als de juiste optie is opgegeven. Ik zal niet in details treden, omdat ze meer betrekking hebben op een tool voor het meten van de dekking dan op CMake. Het is alleen belangrijk om op te merken dat op basis van de resultaten een doel zal worden gecreëerd coverage, waarmee het handig is om de dekking te gaan meten.

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 voor documentatie (doc/CMakeLists.txt)

Doxygen gevonden.

find_package(Doxygen)

Vervolgens controleren we of de gebruiker de taalvariabele heeft ingesteld. Zo ja, dan raken we het niet aan, zo niet, dan nemen we Russisch. Vervolgens configureren we de Doxygen-systeembestanden. Alle noodzakelijke variabelen, inclusief de taal, gaan daar naartoe tijdens het configuratieproces (zie. команду configure_file).

Dan maken we een doel doc, waarmee documentatie wordt gegenereerd. Omdat het genereren van documentatie niet de grootste behoefte is in het ontwikkelingsproces, zal het doel niet standaard ingeschakeld zijn; het zal expliciet moeten worden gelanceerd.

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 voor online sandbox (online/CMakeLists.txt)

Hier vinden we de derde Python en creëren we een doelwit wandbox, dat een verzoek genereert dat overeenkomt met de service-API Wanddoos, en stuurt hem weg. Het antwoord wordt geleverd met een link naar de voltooide sandbox.

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()

Buiten projecteren

Laten we nu eens kijken hoe we dit allemaal kunnen gebruiken.

montage

Het bouwen van dit project bestaat, net als elk ander project op het CMake-bouwsysteem, uit twee fasen:

generatie

cmake -S путь/к/исходникам -B путь/к/сборочной/директории [опции ...]

Als de bovenstaande opdracht niet werkte vanwege een oude versie van CMake, probeer deze dan weg te laten -S:
cmake путь/к/исходникам -B путь/к/сборочной/директории [опции ...]

Meer over opties.

Het bouwen van het project

cmake --build путь/к/сборочной/директории [--target target]

Meer over montagedoelen.

Opties

MIJNLIB_COVERAGE

cmake -S ... -B ... -DMYLIB_COVERAGE=ON [прочие опции ...]

Inclusief doel coverage, waarmee u de codedekking kunt meten door middel van tests.

MIJNLIB_TESTING

cmake -S ... -B ... -DMYLIB_TESTING=OFF [прочие опции ...]

Biedt de mogelijkheid om het bouwen en richten van unittests uit te schakelen check. Als gevolg hiervan wordt het meten van codedekking door tests uitgeschakeld (zie. MYLIB_COVERAGE).

Het testen wordt ook automatisch uitgeschakeld als het project met behulp van het commando als subproject aan een ander project wordt gekoppeld add_subdirectory.

MIJNLIB_DOXYGEN_LANGUAGE

cmake -S ... -B ... -DMYLIB_DOXYGEN_LANGUAGE=English [прочие опции ...]

Verandert de taal van de documentatie die het doel genereert doc naar de gegeven. Voor een lijst met beschikbare talen, zie Doxygen-systeemwebsite.

Russisch is standaard ingeschakeld.

Doelstellingen voor montage

Bij verstek

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

Als het doel niet is opgegeven (wat gelijk is aan het doel all), verzamelt alles wat hij kan, en roept ook het doelwit check.

mylib-unit-tests

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

Stelt unittests samen. Standaard ingeschakeld.

controle

cmake --build путь/к/сборочной/директории --target check

Voert de verzamelde (verzamelde, indien nog niet) eenheidstests uit. Standaard ingeschakeld.

См. также mylib-unit-tests.

dekking

cmake --build путь/к/сборочной/директории --target coverage

Analyseert lopende unit-tests (voert deze uit, indien niet al) op codedekking door tests met behulp van het programma gcovr.

De coatinguitlaat ziet er ongeveer zo uit:

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

Het doel is alleen beschikbaar als de optie is ingeschakeld MYLIB_COVERAGE.

См. также check.

dok

cmake --build путь/к/сборочной/директории --target doc

Start het genereren van codedocumentatie met behulp van het systeem zuurstofoxy.

toverstokje

cmake --build путь/к/сборочной/директории --target wandbox

Het antwoord van de dienst ziet er ongeveer zo uit:

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

Hiervoor wordt gebruik gemaakt van de dienst Wanddoos. Ik weet niet hoe flexibel hun servers zijn, maar ik denk dat deze mogelijkheid niet mag worden misbruikt.

Примеры

Bouw het project in debug-modus met dekkingsmeting

cmake -S путь/к/исходникам -B путь/к/сборочной/директории -DCMAKE_BUILD_TYPE=Debug -DMYLIB_COVERAGE=ON
cmake --build путь/к/сборочной/директории --target coverage --parallel 16

Een project installeren zonder voorafgaande montage en testen

cmake -S путь/к/исходникам -B путь/к/сборочной/директории -DMYLIB_TESTING=OFF -DCMAKE_INSTALL_PREFIX=путь/к/установойной/директории
cmake --build путь/к/сборочной/директории --target install

Bouw de releasemodus in met een bepaalde compiler

cmake -S путь/к/исходникам -B путь/к/сборочной/директории -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-8 -DCMAKE_PREFIX_PATH=путь/к/директории/куда/установлены/зависимости
cmake --build путь/к/сборочной/директории --parallel 4

Het genereren van documentatie in het Engels

cmake -S путь/к/исходникам -B путь/к/сборочной/директории -DCMAKE_BUILD_TYPE=Release -DMYLIB_DOXYGEN_LANGUAGE=English
cmake --build путь/к/сборочной/директории --target doc

Gereedschap

CMaak 3.13

In feite is CMake versie 3.13 alleen nodig om enkele van de consoleopdrachten uit te voeren die in deze help worden beschreven. Vanuit het oogpunt van de syntaxis van CMake-scripts is versie 3.8 voldoende als generatie op andere manieren wordt aangeroepen.
Bibliotheek testen doktest

Het testen kan worden uitgeschakeld (zie опцию MYLIB_TESTING).
zuurstofoxy

Er is een optie beschikbaar om de taal waarin de documentatie wordt gegenereerd te wijzigen MYLIB_DOXYGEN_LANGUAGE.
Taal tolk Python 3

Voor automatische generatie online zandbakken.

Statische analyse

Met CMake en een paar goede tools kun je met minimale inspanning statische analyses uitvoeren.

Cppcontrole

CMake heeft ingebouwde ondersteuning voor een statische analysetool Cppcontrole.

Om dit te doen, moet u de optie gebruiken CMAKE_CXX_CPPCHECK:

cmake -S путь/к/исходникам -B путь/к/сборочной/директории -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_CPPCHECK="cppcheck;--enable=all;-Iпуть/к/исходникам/include"

Hierna wordt de statische analyse automatisch gestart telkens wanneer de broncode wordt gecompileerd en opnieuw gecompileerd. Het is niet nodig om iets extra's te doen.

kletteren

Met behulp van een prachtig hulpmiddel scan-build U kunt ook in een handomdraai een statische analyse uitvoeren:

scan-build cmake -S путь/к/исходникам -B путь/к/сборочной/директории -DCMAKE_BUILD_TYPE=Debug
scan-build cmake --build путь/к/сборочной/директории

Hier moet u, in tegenstelling tot het geval bij Cppcheck, de build elke keer opnieuw uitvoeren scan-build.

nawoord

CMake is een zeer krachtig en flexibel systeem waarmee u functionaliteit voor elke smaak en kleur kunt implementeren. En hoewel de syntaxis soms veel te wensen overlaat, is de duivel nog steeds niet zo verschrikkelijk als hij wordt geschilderd. Gebruik het CMake-bouwsysteem ten behoeve van de samenleving en de gezondheid.

→ Projectsjabloon downloaden

Bron: www.habr.com

CMake en C++ zijn voor altijd broers