🥇CMake ja C++ — igavesed vennad

Arendusprotsessis meeldib mulle vahetada kompilaatorite, kogumise režiimide, sõltuvuste versioonide vahel, teha staatilist analüüsi, mõõta jõudlust, koguda katvust, genereerida dokumentatsiooni jne. Ja mulle meeldib väga CMake, sest see võimaldab mul teha kõike, mida ma tahan.

Paljud inimesed kritiseerivad CMake'i ning tihti on see õigustatud, kuid kui asja lähemalt uurida, pole asi üldse nii halb, ja viimase ajal on see isegi päris hästi edenenud, ning areng suund on täiesti positiivne.

Selles märkuses soovin rääkida sellest, kuidas on üsna lihtne organiseerida C++ peaaguplokki CMake süsteemis, et saavutada järgmine funktsionaalsus:

Kogumine;
Automaatne testide käivitamine;
Koodikatvuse mõõtmine;
Paigaldamine;
Automaatne dokumenteerimine;
Online-keskkonna genereerimine;
Staatiline analüüs.

Kes juba teab Plusidest ja CMake'ist, võib lihtsalt alla laadida projekti mall ja hakkata seda kasutama.

Projekt seestpoolt

Projekti struktuur

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

Põhiliselt räägime sellest, kuidas organiseerida CMake skripte, seetõttu käsitletakse neid põhjalikult. Ülejäänud faile saab iga soovija vaadata otse projekti malli lehelt.

Peamine CMake-fail (./CMakeLists.txt)

Teave projekti kohta

Esiteks tuleb küsida vajalikku versiooni CMake süsteemist. CMake areneb, käskude allkirjad ja käitumine erinevates tingimustes muutuvad. Et CMake kohe mõistaks, mida me temalt ootame, tuleb kohe fikseerida meie ehk nõudmised.

cmake_minimum_required(VERSION 3.13)

Seejärel tähistame oma projekti, selle nime, versiooni, kasutatavad keeled ja muud (vt. käsku project).

Sel juhul määrame keele CXX (see tähendab C++), et CMake ei pingutaks ja ei otsiks C keele kompilaatorit (CMake'is on vaikimisi sisse lülitatud kaks keelt: C ja C++).

project(Mylib VERSION 1.0 LANGUAGES CXX)

Siin on võimalik kohe kontrollida, kas meie projekt on teises projektis alaprojektina kaasatud. See aitab meid tulevikus oluliselt.

get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Projekti valikud

Kaalume kahte valikut.

Esimene valik — MYLIB_TESTING — modulaarsete testide väljalülitamine. See võib olla vajalik, kui oleme kindlad, et testidega on kõik korras, kuid soovime näiteks oma projekti ainult installida või pakkida. Või on meie projekt kaasatud alaprojektina — sellisel juhul pole meie projekti kasutajale huvi meie teste käivitada. Kas te testite sõltuvusi, mida kasutate?

option(MYLIB_TESTING "Luba modulaarne testimine" ON)

Lisaks teeme eraldi valiku MYLIB_COVERAGE kattuvuse mõõtmiseks testidega, kuid see vajab täiendavaid tööriistu, seega tuleb see selgelt lubada.

option(MYLIB_COVERAGE "Luba testidega kattuvuse mõõtmine" OFF)

Kompileerimise valikud

Muidugi oleme me ägedad C++ programmeerijad ja seetõttu tahame kompilaatori poolt maksimaalset kompileerimise aja diagnostikat. Ükski hiir ei lipsa läbi.

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
)

Samuti keelame laiendused, et täielikult vastata C++ keele standardile. CMake'is on need vaikimisi lubatud.

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

Peamine eesmärk

Meie teek koosneb ainult pealkirjafailidest, mistõttu meil ei ole mingit väljundit staatiliste või dünaamiliste teekide näol. Teisest küljest, et meie teeki väljastpoolt kasutada, tuleb see installida, et seda saaks süsteemis avastada ja oma projekti lisada, ning sellega peavad olema koos need sama pealkirjad, samuti võimalikud täiendavad omadused.

Selle eesmärgi saavutamiseks loome liidese teegi.

add_library(mylib INTERFACE)

Seome pealkirjad meie liidese teegiga.

Kaasaegne, trendikas ja nooruslik CMake'i kasutamine eeldab, et pealkirjad, omadused jne edastatakse läbi üheainsa sihtmärk. target_link_libraries(target PRIVATE dependency), ja kõik pealkirjad, mis on seotud sihtmärgiga dependency, on saadaval sihtmärgi kuuluvatele lähtekoodidele target. Ja ei ole vaja mingit [target_]include_directories. See this demonstrated below during the breakdown CMake script for unit tests.

It is also worth noting the so-called generator expressions: $.

This command associates the necessary headers with our interface library, and if our library is linked to any target within the same CMake hierarchy, it will be associated with headers from the directory ${CMAKE_CURRENT_SOURCE_DIR}/include, and if our library is installed in the system and linked in another project using the command find_package, it will be associated with headers from the directory include relative to the installation directory.

target_include_directories(mylib INTERFACE
    $
    $
)

Set the language standard. Of course, the latest one. Moreover, we not only include the standard but also extend it to those who will use our library. This is achieved by the installed property having the category INTERFACE (vt. the target_compile_features command).

target_compile_features(mylib INTERFACE cxx_std_17)

Create an alias for our library. For aesthetics, it will be in a special "namespace". This will be useful when different modules appear in our library, and we want to connect them independently of each other. As in Boost, for example.

add_library(Mylib::mylib ALIAS mylib)

Paigaldamine

Installing our headers to the system. It's simple. We specify that the folder with all the headers should go to the directory include relative to the installation location.

install(DIRECTORY include/mylib DESTINATION include)

Next, we inform the build system that we want to be able to call the command in external projects find_package(Mylib) and obtain the target Mylib::mylib.

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

The next spell should be understood this way. When in an external project we call the command find_package(Mylib 1.2.3 REQUIRED), and the actual version of the installed library turns out to be incompatible with the version 1.2.3, CMake will automatically generate an error. This means there is no need to manually track versions.

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)

Testid

If the tests are explicitly disabled with the corresponding option või meie projekt on alamprojekt, see tähendab, et see on ühendatud teise CMake projekti kaudu käsu add_subdirectory, me ei liigu hierarhias edasi ja skript, milles on kirjeldatud käsud testide genereerimiseks ja käivitamiseks, lihtsalt ei käivitu.

if(NOT MYLIB_TESTING)
    message(STATUS "Mylibi projekti testimine on keelatud")
elseif(IS_SUBPROJECT)
    message(STATUS "Mylibi ei testita alammodulina")
else()
    add_subdirectory(test)
endif()

Dokumentatsioon

Dokumentatsiooni ei genereerita ka alamprojekti puhul.

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

Online-keskkond

Sarnaselt ei ole alamprojekti juhul ka veebiliivakaste.

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

Testide skript (test/CMakeLists.txt)

Testimine

Esiteks otsime paketti vajaliku testimisraamistiku jaoks (asendage oma lemmikuga).

find_package(doctest 2.3.3 REQUIRED)

Loome oma käivitatava faili testide jaoks. Tavaline on, et käivitatavasse binaari lisan ainult faili, kus on funktsioon main.

add_executable(mylib-unit-tests test_main.cpp)

Ja failid, kus on kirja pandud testid, lisan hiljem. Kuid nii teha ei ole vajalik.

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

Seome sõltuvused. Pange tähele, et meie binaariga seostasime ainult vajalikud CMake eesmärgid ega kutsunud üles käsku target_include_directories. Testimisraamistiku pealkirjad ja meie Mylib::mylib, samuti kogumise parameetrid (meie juhul on see C++ keele standard) läksid koos nende eesmärkidega läbi.

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

Lõpuks loome vale eesmärgi, mille "kogumine" on võrdne testide käitamisega, ja lisame selle doelame standardkogumisse (seda juhib atribuut , või). See tähendab, et vaikimisi kogumine käivitab testide käitamist, seega me kunagi ei unusta neid käivitada.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Katvus

Seejärel aktiveerime koodikatvuse mõõtmise, kui vastav valik on määratud. Sügavale detailidesse ei lähe, kuna need kuuluvad rohkem katvuse mõõtamisseadmesse kui CMake'ile. Oluline on märkida ainult, et tulemuste põhjal luuakse eesmärk coverage, millega on mugav käivitada katvuse mõõtmine.

find_program(GCOVR_EXECUTABLE gcovr)
if(MYLIB_COVERAGE AND GCOVR_EXECUTABLE)
    message(STATUS "Koodikatse katvuse mõõtmine on sisse lülitatud")

    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 "Koodikatse katvuse mõõtmiseks on vajalik programm gcovr")
endif()

Dokumentatsiooni skript (doc/CMakeLists.txt)

Leitud Doxygen.

find_package(Doxygen)

Edasi kontrollime, kas kasutaja on määranud keelemuutuja. Kui jah, siis ei puutu sellesse, kui ei, siis võtame vene. Seejärel konfigureerime Doxygen süsteemi failid. Kõik vajalikud muutujad, sealhulgas keel, saadakse konfiguratsiooni käigus (vt. komando configure_file).

Peale seda loome sihiks doc, mis käivitab dokumentatsiooni genereerimise. Kuna dokumentatsiooni genereerimine ei ole arenduse käigus kõige tähtsam vajadus, siis ei ole siht vaikimisi sisse lülitatud, see tuleb käivitada selgelt.

if (Doxygen_FOUND)
    if (NOT MYLIB_DOXYGEN_LANGUAGE)
        set(MYLIB_DOXYGEN_LANGUAGE Vene)
    endif()
    message(STATUS "Doxygeni dokumentatsioon genereeritakse keeles ${MYLIB_DOXYGEN_LANGUAGE}")
    configure_file(Doxyfile.in Doxyfile)
    add_custom_target(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}\/Doxyfile)
endif ()

Online-keskkonna skript (online/CMakeLists.txt)

Siin leiame kolmanda Python'i ja loome sihiks wandbox, mis genereerib päringu, mis vastab teenuse API-le Wandbox, ja saadab selle. Vastuseks tulevad valmis liivakasti link.

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 "Veebiliivakasti loomiseks on vajalik Python 3 interpreteur")
endif()

Projekt väljaspool

Nüüd vaatame, kuidas seda kõike kasutada.

Kogumine

Selle projekti koostamine, nagu ka iga teise CMake süsteemi projekti puhul, koosneb kahest etapist:

Genereerimine

cmake -S tee\/kallid -B tee\/kogumiskohta [valikud ...]

Kui ülemine käsk ei toiminud vanema CMake versiooni tõttu, proovige jätta välja -S:
cmake tee\/kallid -B tee\/kogumiskohta [valikud ...]

Rohkem valikute kohta.

Projekti koostamine

cmake --build tee\/kogumiskohta [--target siht]

Rohkem koostamis eesmärkide kohta.

Valikud

MYLIB_COVERAGE

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

Lülitab sihi sisse coverage, mille on võimalik käivitada koodikatvuse mõõtmine testide kaudu.

MYLIB_TESTING

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

Pakub võimalusi moodulite testimise ja eesmärgi väljalülitamiseks. check. Selle tulemusena lülitatakse koodikatvuse mõõtmine testide kaudu välja (vt. MYLIB_COVERAGE).

Samuti lülitatakse testimine automaatselt välja, kui projekt lisatakse teise projekti alaprojektina käsu abil add_subdirectory.

MYLIB_DOXYGEN_LANGUAGE

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

Vahetab dokumentatsiooni keele, mille genereerib eesmärk doc mugandatuks. Saadaval olevate keelte loetelu leiate Doxygen süsteemi veebisaidilt..

Vaikimisi on keel vene.

Kogumise eesmärgid

Vaikimisi

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

Kui eesmärki ei ole määratud (mis on samaväärne eesmärgiga all), kogub kõik, mis on võimalik, ning kutsub üles eesmärki. check.

mylib-unit-tests

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

Kompileerib moodulitestide. Vaikimisi on see sisse lülitatud.

check

cmake --build tee/ehituskausta --target check

Käivitab koostatud (kogub, kui veel mitte) moodulitestid. Vaikimisi on see sisse lülitatud.

Vaata ka mylib-unit-tests.

coverage

cmake --build tee/ehituskausta --target coverage

Analüüsib käivitatud (käivitab, kui veel mitte) moodulitestid koodikatvuse osas testimise ajal programmi gcovr.

Katvuse väljund näeb välja selline:

------------------------------------------------------------------------------
                           GCC Koodikatvuse Aruanne
Kaust: /path/to/cmakecpptemplate/include/
------------------------------------------------------------------------------
Fail                                       Read       Täitmine  Katvus   Puuduvad
------------------------------------------------------------------------------
mylib/myfeature.hpp                            2       2   100%   
------------------------------------------------------------------------------
TOTAL                                          2       2   100%
------------------------------------------------------------------------------

Eesmärk on saadaval ainult, kui valik on sisse lülitatud. MYLIB_COVERAGE.

Vaata ka check.

doc

cmake --build tee/ehituskausta --target doc

Käivitab dokumentatsiooni genereerimise koodi jaoks Doxygen süsteemi abil. Doxygen.

wandbox

cmake --build tee/ehituskausta --target wandbox

Teenuse vastus näeb välja selline:

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

Selleks kasutatakse teenust Wandbox. Ma ei tea, kui paindlikud nende serverid on, kuid ma arvan, et seda võimalust ei tasu kuritarvitada.

Näited

Projekti ülesehitus tõrkeotsingu režiimis koodikatvuse mõõtmisega.

cmake -S tee/komplekt/dokumendid -B tee/ehituskausta -DCMAKE_BUILD_TYPE=Debug -DMYLIB_COVERAGE=ON
cmake --build tee/ehituskausta --target coverage --parallel 16

Projekti paearendust ja testimist

cmake -S tee/koodifailid -B tee/ehituskaust -DMYLIB_TESTING=OFF -DCMAKE_INSTALL_PREFIX=tee/paigalduskaust
cmake --build tee/ehituskaust --target install

Ehitus vabastamisrežiimis määratud kompilaatoriga

cmake -S tee/koodifailid -B tee/ehituskaust -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-8 -DCMAKE_PREFIX_PATH=tee/kaust/kuhu/paigaldatud/sõltuvused
cmake --build tee/ehituskaust --parallel 4

Dokumentatsiooni genereerimine inglise keeles

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

Tööriistad

CMake 3.13
Tegelikult vajatakse CMake versiooni 3.13 ainult teatud konsolikomandide käivitamiseks, mis on kirjeldatud antud juhendis. CMake-skriptide süntaksiks piisab versioonist 3.8, kui genereerimist kutsuda välja muude viiside kaudu.
Testimise raamatukogu doctest
Testimist saab keelduda (vt. valikut MYLIB_TESTING).
Doxygen
Dokumentatsioonikeele vahetamiseks on olemas valik MYLIB_DOXYGEN_LANGUAGE.
Tõlkija YP Python 3
Automaatseks genereerimiseks veebipesakond.

Staatiline analüüs

CMake ja paar head tööriista võivad hõlpsasti tagada staatilise analüüsi minimaalse vaevaga.

Cppcheck

CMake'is on sisseehitatud tugi staatilise analüüsi tööriistale Cppcheck.

Selleks tuleb kasutada valikut CMAKE_CXX_CPPCHECK:

cmake -S tee/koodifailid -B tee/ehituskaust -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_CPPCHECK="cppcheck;--enable=all;-Itee/koodifailid/include"

Pärast seda käivitatakse staatiline analüüs automaatselt iga kord, kui lähtefaile kompileeritakse ja uuesti kompileeritakse. Ei ole vaja midagi lisada.

Clang

Imekauni tööriista abil scan-build saab samuti staatilist analüüsi kiiresti käivitada:

scan-build cmake -S tee/koodifailid -B tee/ehituskaust -DCMAKE_BUILD_TYPE=Debug
scan-build cmake --build tee/ehituskaust

Siin on vastupidiselt Cppcheck'ile vajalik igakordselt käivitada ehitus scan-build.

Eessõna

CMake on väga võimas ja paindlik süsteem, mis võimaldab realiseerida igasugust funktsionaalsust. Ja kuigi süntaks jätab vahel soovida, ei ole see nii hirmus, kui teda maalitakse. Kasutage CMake ehitussüsteemi ühiskonna hüvanguks ja enda terviseks.

→ Laadi alla projekti mall

Allikas: habr.com