🥇CMake ja C++ — vennad igavesti

Arenduse käigus meeldib mulle vahetada kompilaatoreid, koostamisrežiime, sõltuvuste versioone, teostada staatilist analüüsi, mõõta jõudlust, koguda katvust, genereerida dokumentatsiooni jne. Ja mulle väga meeldib CMake, sest see võimaldab mul teha kõike seda, mida ma tahan.

Paljud kritiseerivad CMake’i ja tihti õigustatult, kuid kui süveneda, siis ei ole kõik nii hull ja viimasel ajal isegi üsna hästi, ning arengu suund on igati positiivne.

Käesolevas märkuses tahan rääkida, kuidas on üsna lihtne korraldada C++ keeles pealkirjafaili CMake süsteemis, et saavutada järgmine funktsionaalsus:

Koostamine;
Automaatne testide käivitamine;
Koodikatvuse mõõtmine;
Installeerimine;
Autodokumenteerimine;
Veebihoiuruumi genereerimine;
Staatiline analüüs.

Kes juba teab plussidest ja CMake’ist, võib lihtsalt alla laadida projekti malli ja hakata 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

Peamiselt käsitletakse, kuidas organiseerida CMake-skripte, seega uurime neid üksikasjalikult. Ülejäänud faile saavad huvilised otseselt vaadata projekti-malli lehelt.

Peamine CMake fail (./CMakeLists.txt)

Projektiteave

Esiteks tuleb küsida vajaliku CMake süsteemi versiooni. CMake areneb, muutuvad käskude signatuurid ja käitumine erinevates tingimustes. Et CMake mõistaks kohe, mida me temalt tahame, peame kohe fikseerima meie nõudmised.

cmake_minimum_required(VERSION 3.13)

Seejärel määratleme meie projekti, selle nime, versiooni, kasutatavad keeled ja muud (vt. käsku project).

Selles olukorras määrame keele CXX (mis tähendab C++), et CMake ei peaks muretsema ja ei peaks otsima C keele kompilaatorit (CMake sisaldab vaikimisi kahte keelt: C ja C++).

project(Mylib VERSION 1.0 LANGUAGES CXX)

Siit saate kohe kontrollida, kas meie projekt on mõnes teises projektis alamprojekti kujul. See aitab edaspidi palju.

get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Projekti valikud

Arvutame välja kaks valikut.

Esimene valik — MYLIB_TESTIMINE — moodultestide välja lülitamiseks. See võib olla vajalik, kui oleme kindlad, et testid on korras ja soovime näiteks ainult oma projekti installida või paketitada. Või on meie projekt alamprojektina kaasatud — sel juhul ei ole meie projekti kasutaja huvitatud meie testide käivitamisest. Kas te ei testeeri sõltuvusi, mida kasutate?

option(MYLIB_TESTING "Aktiveeri moodulitestimine" ON)

Lisaks teeme eraldi valiku MYLIB_KATTE testikattete mõõtmiseks, kuid see vajab lisatööriistu, seega tuleb see selgesõnaliselt aktiveerida.

option(MYLIB_COVERAGE "Aktiveeri testikattete mõõtmine" OFF)

Kompilatsiooni valikud

Muidugi oleme me lahedad C++ programmeerijad, seega soovime kompilatsioonivaatleja maksimaalset diagnoosimist kompilatsiooni ajal. Ükski hiir ei pääse 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
)

Laieltame laiendused välja, et täielikult vastata C++ keele standardile. CMake'is on need vaikimisi sisse lülitatud.

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

Peamine siht

Meie teek koosneb ainult päistefailidest, seega ei ole meil mingit väljundit staatiliste või dünaamiliste teekide näol. Teisest küljest, et kasutada meie teeki väljastpoolt, tuleb see installida, et see oleks süsteemis avastatav ja seostatav oma projektiga, samas koos kaasnevate päiste ning võimalik, et ka mõne täiendava omadusega.

Selle eesmärgi saavutamiseks loome liidese teegi.

add_library(mylib INTERFACE)

Seome päised meie liidese teegiga.

Kaasaegne, trendikas ja noortele suunatud CMake'i kasutamine eeldab, et päised, omadused jt edastatakse läbi üheainsa sihisse. Seega piisab öelda target_link_libraries(target PRIVATE dependency), ja kõik pealkirjad, mis on seotud eesmärgiga sõltuvus, on saadaval allikate jaoks, mis kuuluvad eesmärgile target. Ja mingeid ei nõuta [target_]include_directories. Seda demonstreeritakse allpool, kui käsitletakse CMake-skripti modulaarsete testide jaoks.

Samuti tasub tähele panna nn avaldis-jaanid: $.

See käsk seondab vajalikud pealkirjad meie liidesti raamatukoguga; kui meie raamatukogu on ühendatud mõne eesmärgiga sama CMake hierarhia raames, siis seondatakse selle liidese pealkirjad direktorist ${CMAKE_CURRENT_SOURCE_DIR}/include, ja kui meie raamatukogu on installitud süsteemi ja ühendatud teises projektis käsuga find_package, siis seondatakse selle pealkirjad direktorist include installatsiooni direktorist.

target_include_directories(mylib INTERFACE
    $
    $
)

Seame keele standardi. Loomulikult, kõige uuema. Samuti mitte lihtsalt standardi kaasamine, vaid ka selle laiendamine nendele, kes meie raamatukogu kasutavad. See saavutatakse seetõttu, et seatud omadus kuulub kategooriasse INTERFACE (vt. komandat target_compile_features).

target_compile_features(mylib INTERFACE cxx_std_17)

Loome alias meie teegile. Ja kauni väljanägemise nimel asetame selle spetsiaalsesse „nimetükki“. See on kasulik, kui meie teegis ilmuvad erinevad moodulid, ja me saame neid iseseisvalt lisada. Nagu Boostis näiteks.

add_library(Mylib::mylib ALIAS mylib)

Installeerimine

Meie päisefailide installimine süsteemi. Siin on kõik lihtne. Ütleme, et kaust, kus kõik päisefailid asuvad, peab jõudma installatsioonikausta include installatsiooni asukoha suhtes.

install(DIRECTORY include/mylib DESTINATION include)

Seejärel teavitame ehitussüsteemi, et soovime, et võime kolmandates projektides kutsuda käsklust find_package(Mylib) ja saada eesmärgi Mylib::mylib.

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

Järgmine peatükk tuleb mõista nii. Kui kolmandas projektis kutsume käskluse find_package(Mylib 1.2.3 REQUIRED), ja samas osutub installitud teegi tegelik versioon mitte ühilduv versiooniga 1.2.3, genereerib CMake automaatselt vea. See tähendab, et versioonide jälgimisega ei pea enam käsitsi tegelema.

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

Kui testid on välja lülitatud vastava valiku abil või meie projekt on alaprojekt, st see on seotud teise CMake-projektiga käsklusega add_subdirectory, siis me ei jätka hierarhias edasi ning skript, milles on kirjas testide genereerimise ja käitamise käsklused, ei käivitu.

if(NOT MYLIB_TESTING)
    message(STATUS "Mylibi projekti testimine on välja lülitatud")
elseif(IS_SUBPROJECT)
    message(STATUS "Mylib ei testita alamooduli režiimis")
else()
    add_subdirectory(test)
endif()

Dokumentatsioon

Dokumentatsiooni ei genereerita samuti alaprojekti puhul.

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

Veebihoiuruum

Sarnaselt ei ole alaprojektil ka veebihõlvijad.

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

Testide skript (test/CMakeLists.txt)

Testimine

Esmalt leiame paketi vajaliku testimisraamistiku jaoks (asendage oma lemmikuga).

find_package(doctest 2.3.3 REQUIRED)

Loomeme meie täitmisfail testide jaoks. Tavalise täitmise binaari lisan ma tavaliselt ainult faili, kus on funktsioon main.

add_executable(mylib-unit-tests test_main.cpp)

Failid, kus testid on kirjeldatud, lisan hiljem. Kuid see pole kohustuslik.

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

Ühendame sõltuvused. Pange tähele, et meie binaarprogrammi oleme sidunud vaid vajalike CMake-eesmärkidega, ja ei käivitanud käsku target_include_directories. Testimisraamistiku ja meie Mylib::mylib, samuti kogumispõhimõtted (meie puhul on see keelestandardi C++) läksid koos nende eesmärkidega.

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

Lõpuks loome vale eesmärgi, mille "kogumine" on võrdne testide käivitamisega, ja lisame selle eesmärgi vaikimisi kogumisse (selle eest vastutab atribuut ALL). See tähendab, et vaikimisi kogumine käivitab testide käivitamise, seega me kunagi ei unusta neid käivitada.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Katvus

Järgmisena lülitame sisse koodi katvuse mõõtmise, kui vastav valik on määratud. Üksikasjadesse ei lasku, kuna need on rohkem seotud katvuse mõõtmise tööriistaga kui CMake'iga. Oluline on märkida, et tulemuste põhjal luuakse eesmärk coverage, millega on mugav katvuse mõõtmist käivitada.

find_program(GCOVR_EXECUTABLE gcovr)
if(MYLIB_COVERAGE AND GCOVR_EXECUTABLE)
    message(STATUS "Koodikattuvuse 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 "Koodikattuvuse mõõtmiseks on vajalik programm gcovr")
endif()

Dokumentatsiooni skript (doc/CMakeLists.txt)

Leitud Doxygen.

find_package(Doxygen)

Seejärel kontrollime, kas kasutaja on määranud keele muutujat. Kui jah, siis ei muuda midagi; kui ei, siis valime vene. Seejärel seadistame Doxygen süsteemi failid. Kõik vajalikud muutujad, sealhulgas keel, sisestatakse sinna seadistamise protsessi käigus (vt. configure_file käsku).

Pärast seda loome sihte dok, mis käivitab dokumentatsiooni genereerimise. Kuna dokumentatsiooni genereerimine ei ole arenduse käigus kõige hädavajalikum, siis on eesmärk vaikesätte järgi välja lülitatud ja tuleb selgelt käivitada.

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

Veebihoiuruumi skript (online/CMakeLists.txt)

Siin leiame kolmanda Pythoni ja loome eesmärgi wandbox, mis genereerib päringu, mis vastab teenuse API-le Wandbox, ja saadab selle ära. Vastuseks tuleb link valmis liivakasti.

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 "Veebipoli liivakasti loomiseks on vajalik 3. versiooni Python tõlgendaja")
endif()

Projekt väljastpoolt

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

Koostamine

Selle projekti koostamine, nagu iga teise CMake'i koostamissüsteemis, koosneb kahest etapist:

Generatsioon

cmake -S tee/kallid -B tee/kallid/koostamisdirektorid [valikud ...]

Kui eespool olev käsk ei töötanud vanema CMake'i versiooni tõttu, proovige kirjutada -S:
cmake tee/kallid -B tee/kallid/koostamisdirektorid [valikud ...]

Lisainfot valikute kohta.

Projekti koostamine

cmake --build tee/k/ehitamis/kaust

Rohkem teavet ehitussihtide kohta.

Valikud

MYLIB_KATTE

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

Sisaldab sihti coverage, mille abil saab teha koodikattete mõõtmisi testide kaudu.

MYLIB_TESTIMINE

cmake -S ... -B ... -DMYLIB_TESTIMINE=OFF [teised valikud ...]

Pakub võimalust välja lülitada moodulitestide ehitus ja siht kontrolli. Seetõttu lülitatakse välja koodikattete mõõtmine (vt MYLIB_KATTE).

Testimine lülitatakse automaatselt välja ka siis, kui projekt lisatakse teise projekti alaprojektina käsuga add_subdirectory.

MYLIB_DOXYGEN_VEEBIMISKEEL

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

Lülitab dokumentatsiooni keele, mida siht genereerib dok määratletud keelele. Saadaval olevate keelte loetelu leiate Doxygen süsteemi veebisaidilt.

Vaikimisi on lubatud vene keel.

Kogumis eesmärgid

Vaikimisi

cmake --build tee/k/ehitamis/kaust
cmake --build tee/k/ehitamis/kaust --target all

Kui siht pole määratud (mis on ekvivalentne sihiga all), ehitab kõik saadaval olevad ja kutsub esile sihi kontrolli.

mylib-unit-tests

cmake --build tee/k/ehitamis/kaust --target mylib-unit-tests

Kompileerib moodulitestid. Vaikimisi lubatud.

kontrolli

cmake --build tee/k/ehitamis/kaust --target check

Käivitab koostatud (ehitab, kui veel mitte) moodulitestid. Vaikimisi lubatud.

Vaata ka mylib-unit-tests.

coverage

cmake --build tee/k/kokkglib/direktori --target coverage

Analüüsib käivitatud (käivitab, kui veel mitte) mooduliteste testika katte osas gcovr.

Kattekäive näeb välja umbes nii:

------------------------------------------------------------------------------
                           GCC Koodi Katte Aruanne
Kataloog: /path/to/cmakecpptemplate/include/
------------------------------------------------------------------------------
Fail                                        Read    Täitmine  Katte  Puudu
------------------------------------------------------------------------------
mylib/myfeature.hpp                            2       2   100%   
------------------------------------------------------------------------------
KOKKU                                         2       2   100%
------------------------------------------------------------------------------

Sihtmärk on saadaval ainult lubatud valiku korral MYLIB_KATTE.

Vaata ka kontrolli.

dok

cmake --build tee/k/kokkglib/direktori --target doc

Käivitab koodi dokumentatsiooni genereerimise süsteemi kaudu Doxygen.

wandbox

cmake --build tee/k/kokkglib/direktori --target wandbox

Teenuse vastus näeb välja umbes nii:

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

Selleks kasutatakse teenust Wandbox. Ei tea, kui vastupidavad nende serverid on, kuid arvan, et selle võimaluse kuritarvitamine pole mõistlik.

Näited

Projekt tuleb üles ehitada silumisrežiimis katte mõõtmisega

cmake -S tee/ka/allikad -B tee/ka/ehitus/kaust -DCMAKE_BUILD_TYPE=Debug -DMYLIB_COVERAGE=ON
cmake --build tee/ka/ehitus/kaust --target coverage --parallel 16

Projekti installimine ilma eelneva ehitamise ja testimiseta

cmake -S tee/ka/allikad -B tee/ka/ehitus/kaust -DMYLIB_TESTING=OFF -DCMAKE_INSTALL_PREFIX=tee/ka/installimise/kaust
cmake --build tee/ka/ehitus/kaust --target install

Ehitus vabastamise režiimis määratud kompilaatoriga

cmake -S tee/ka/allikad -B tee/ka/ehitus/kaust -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-8 -DCMAKE_PREFIX_PATH=tee/ka/kausta/kuhu/on/paigaldatud/sõltuvused
cmake --build tee/ka/ehitus/kaust --parallel 4

Dokumentatsiooni genereerimine inglise keeles

cmake -S tee/ka/allikad -B tee/ka/ehitus/kaust -DCMAKE_BUILD_TYPE=Release -DMYLIB_DOXYGEN_LANGUAGE=English
cmake --build tee/ka/ehitus/kaust --target doc

Tööriistad

CMake 3.13
Tegelikult on CMake 3.13 versioon vajalik ainult mõnede käsurea käskude käivitamiseks, mis on selles juhendis kirjeldatud. CMake-skriptide süntaksist piisab versiooni 3.8 kasutamisest, kui genereerimist kutsutakse muude viisidega.
Testimise raamatukogu doctest
Testimise saab välja lülitada (vt valik MYLIB_TESTING).
Doxygen
Keele, millel dokumentatsioon genereeritakse, saab valida MYLIB_DOXYGEN_VEEBIMISKEEL.
Programmeerimiskeelte tõlgendus Python 3
Automaatseks genereerimiseks veebihüljest.

Statiline analüüs

CMake’i ja paar hea tööriista abil saab staatilise analüüsi teha minimaalse vaevaga.

Cppcheck

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

Selleks tuleb kasutada valikut CMAKE_CXX_CPPCHECK:

cmake -S tee/koodiallikatele -B tee/ehitustehnikate -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_CPPCHECK="cppcheck;--enable=all;-Itee/koodiallikate/include"

Pärast seda käivitub staatiline analüüs automaatselt iga kord, kui kompileeritakse ja uuesti kompileeritakse lähtekoodi. Ükski lisategevus pole vajalik.

Clang

Kasutades imelist tööriista scan-build saab samuti staatilist analüüsi kiirelt käivitada:

scan-build cmake -S tee/koodiallikatele -B tee/ehitustehnikate -DCMAKE_BUILD_TYPE=Debug
scan-build cmake --build tee/ehitustehnikate

Siin, erinevalt Cppcheckist, on iga kord vajalik käivitada ehitus läbi scan-build.

Järelsõna

CMake on väga võimas ja paindlik süsteem, mis võimaldab realiseerida funktsionaalsust igasuguste soovide ja vajaduste järgi. Ja kuigi süntaks jätab mõnikord soovida, ei ole asi tegelikult nii hull, kui teda maalitakse. Kasutage CMake’i koostesüsteemi ühiskonna hüvanguks ja oma tervise nimel.

→ Laadi alla projekti mall

Allikas: habr.com