🥇CMake en C++ is broers vir ewig

Tydens ontwikkeling hou ek daarvan om samestellers te verander, modusse te bou, afhanklikheidsweergawes, statiese analise uit te voer, prestasie te meet, dekking te versamel, dokumentasie te genereer, ensovoorts. En ek is baie lief vir CMake, want dit laat my toe om te doen wat ek wil.

Baie skel CMake, en dikwels welverdiend, maar as jy kyk, is dit nie so erg nie, maar die afgelope tyd glad nie sleg nie, en die rigting van ontwikkeling is redelik positief.

In hierdie nota wil ek jou vertel hoe maklik dit is om 'n C ++-kopbiblioteek in 'n CMake-stelsel te organiseer om die volgende funksionaliteit te kry:

samestelling;
Autorun toetse;
Kode dekking meting;
installasie;
Outodokumentasie;
Aanlyn sandbox generasie;
Statiese analise.

Wie reeds die voordele en si-maak verstaan, kan net laai projek sjabloon af en begin dit gebruik.

Projek van binne af

Projekstruktuur

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

Dit sal hoofsaaklik fokus op hoe om CMake-skrifte te organiseer, sodat hulle in detail ontleed sal word. Die res van die lêers kan direk deur enigiemand bekyk word. op die sjabloonprojekbladsy.

Hoof CMake-lêer (./CMakeLists.txt)

Projek inligting

Eerstens moet u die verlangde weergawe van die CMake-stelsel aanvra. CMake ontwikkel, opdraghandtekeninge verander, gedrag onder verskillende omstandighede. Om vir CMake onmiddellik te verstaan wat ons daarvan wil hê, moet ons dadelik ons vereistes daarvoor regmaak.

cmake_minimum_required(VERSION 3.13)

Dan dui ons ons projek aan, sy naam, weergawe, tale wat gebruik word, ens. команду project).

In hierdie geval, spesifiseer die taal CXX (wat C++ beteken) sodat CMake nie die moeite doen om na 'n C-samesteller te soek nie (by verstek is twee tale by CMake ingesluit: C en C++).

project(Mylib VERSION 1.0 LANGUAGES CXX)

Hier kan u dadelik kyk of ons projek as 'n subprojek by 'n ander projek ingesluit is. Dit sal baie help in die toekoms.

get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Projek Opsies

Kom ons kyk na twee opsies.

Die eerste opsie is MYLIB_TESTING - om eenheidstoetse uit te skakel. Dit kan nodig wees as ons seker is dat alles in orde is met die toetse, en ons wil byvoorbeeld net ons projek installeer of verpak. Of ons projek is ingesluit as 'n subprojek - in hierdie geval stel die gebruiker van ons projek nie daarin belang om ons toetse uit te voer nie. Jy toets nie die afhanklikhede wat jy gebruik nie, doen jy?

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

Daarbenewens sal ons 'n aparte opsie maak MYLIB_COVERAGE vir die meting van kodedekking met toetse, maar dit sal bykomende gereedskap vereis, so jy sal dit eksplisiet moet aktiveer.

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

Samestelling opsies

Natuurlik is ons cool programmeerders-positief, so ons wil die maksimum vlak van samestelling-tyd diagnostiek van die samesteller hê. Nie 'n enkele muis sal deurkom nie.

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
)

Ons sal ook uitbreidings deaktiveer om ten volle aan die C++-taalstandaard te voldoen. Hulle is by verstek in CMake geaktiveer.

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

primêre doel

Ons biblioteek bestaan slegs uit koplêers, wat beteken dat ons geen uitvoer in die vorm van statiese of dinamiese biblioteke het nie. Aan die ander kant, om ons biblioteek van buite te gebruik, moet jy dit installeer, jy moet dit in die stelsel kan vind en aan jou projek koppel, en terselfdertyd hierdie einste kopskrifte, ook as, moontlik, 'n paar bykomende eiendomme.

Vir hierdie doel skep ons 'n koppelvlakbiblioteek.

add_library(mylib INTERFACE)

Ons bind die opskrifte aan ons koppelvlakbiblioteek.

Moderne, nuwerwetse, jeugdige gebruik van CMake beteken dat opskrifte, eienskappe, ens. deur 'n enkele teiken oorgedra word. Dit is dus genoeg om te sê target_link_libraries(target PRIVATE dependency), en alle opskrifte wat met die teiken geassosieer word dependency, sal beskikbaar wees vir bronne wat aan die teiken behoort target. En jy het niks nodig nie [target_]include_directories. Dit sal hieronder gedemonstreer word tydens ontleding CMaak 'n skrif vir eenheidstoetse.

Dit is ook die moeite werd om aandag te skenk aan die sg. выражения-генераторы: $<...>.

Hierdie opdrag assosieer die opskrifte wat ons benodig met ons koppelvlakbiblioteek, en as ons biblioteek aan enige teiken binne dieselfde CMake-hiërargie gekoppel is, sal die opskrifte van die gids daarmee geassosieer word ${CMAKE_CURRENT_SOURCE_DIR}/include, en as ons biblioteek op die stelsel geïnstalleer is en aan 'n ander projek gekoppel is deur die opdrag te gebruik find_package, dan sal die opskrifte van die gids daarmee geassosieer word include relatief tot die installasiegids.

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

Stel die taalstandaard. Natuurlik die nuutste. Terselfdertyd sluit ons nie net die standaard in nie, maar versprei dit ook aan diegene wat ons biblioteek gaan gebruik. Dit word bereik deur die vasgestelde eiendom 'n kategorie te hê INTERFACE (Cm. target_compile_features opdrag).

target_compile_features(mylib INTERFACE cxx_std_17)

Ons kry 'n alias vir ons biblioteek. En vir skoonheid sal dit in 'n spesiale "naamruimte" wees. Dit sal nuttig wees wanneer verskillende modules in ons biblioteek verskyn, en ons gaan om hulle onafhanklik van mekaar te verbind. Soos in Busta, byvoorbeeld.

add_library(Mylib::mylib ALIAS mylib)

installasie

Die installering van ons opskrifte in die stelsel. Alles is eenvoudig hier. Ons sê dat die gids met al die kopskrifte in die gids moet val include met betrekking tot die installasie plek.

install(DIRECTORY include/mylib DESTINATION include)

Vervolgens vertel ons die boustelsel dat ons die opdrag in derdeparty-projekte wil kan oproep find_package(Mylib) en kry 'n teiken Mylib::mylib.

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

Die volgende beswering moet so verstaan word. Wanneer ons in 'n syprojek is, noem ons die opdrag find_package(Mylib 1.2.3 REQUIRED), en terselfdertyd sal die regte weergawe van die geïnstalleerde biblioteek onversoenbaar wees met die weergawe 1.2.3, CMake sal outomaties 'n fout genereer. Dit wil sê, jy hoef nie handmatig tred te hou met weergawes nie.

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)

toetse

As toetse uitdruklik gedeaktiveer is met ooreenstemmende opsie of ons projek is 'n subprojek, dit wil sê, dit is gekoppel aan 'n ander CMake-projek deur die opdrag te gebruik add_subdirectory, gaan ons nie verder in die hiërargie af nie, en die skrif, wat die opdragte vir die generering en uitvoer van toetse beskryf, begin eenvoudig nie.

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

Dokumentasie

Dokumentasie sal ook nie gegenereer word in die geval van 'n subprojek nie.

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

Aanlyn sandbox

Net so sal die subprojek ook nie 'n aanlyn sandbox hê nie.

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

Skrip vir toetse (test/CMakeLists.txt)

toets

Eerstens vind ons 'n pakket met die gewenste toetsraamwerk (vervang dit met jou gunsteling een).

find_package(doctest 2.3.3 REQUIRED)

Ons skep ons uitvoerbare lêer met toetse. Gewoonlik, direk by die uitvoerbare binêre voeg ek slegs die lêer by waarin die funksie sal wees main.

add_executable(mylib-unit-tests test_main.cpp)

En die lêers waarin die toetse self beskryf word, voeg ek later by. Maar dit is nie nodig om dit te doen nie.

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

Ons verbind afhanklikhede. Neem asseblief kennis dat ons slegs die CMake-teikens wat ons nodig gehad het aan ons binêre geheg het, en nie die opdrag geroep het nie target_include_directories. Opskrifte van die toetsraamwerk en van ons Mylib::mylib, sowel as bouopsies (in ons geval, die C++-taalstandaard) het saam met hierdie teikens gekruip.

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

Laastens skep ons 'n dummy-teiken waarvan die "bou" gelykstaande is aan lopende toetse, en voeg hierdie teiken by die verstekbou (dit is die verantwoordelikheid van die kenmerk ALL). Dit beteken dat die verstekbou die toetse sal laat loop, wat beteken dat ons nooit sal vergeet om dit uit te voer nie.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Dekking

Skakel dan kodedekkingmeting aan as die ooreenstemmende opsie ingestel is. Ek gaan nie op die besonderhede in nie, want dit is meer verwant aan die dekkingsmetingsinstrument as aan CMake. Dit is net belangrik om daarop te let dat die resultate 'n doel sal skep coverage, waarmee dit gerieflik is om dekking te begin meet.

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

Dokumentasieskrif (doc/CMakeLists.txt)

Doxygen gevind.

find_package(Doxygen)

Vervolgens kyk ons of die veranderlike met die taal deur die gebruiker gestel is. Indien wel, dan raak ons nie daaraan nie, indien nie, dan neem ons Russies. Dan konfigureer ons die Doxygen-stelsellêers. Al die nodige veranderlikes, insluitend die taal, kom daar tydens die konfigurasieproses (sien. команду configure_file).

Dan skep ons 'n doelwit doc, wat dokumentasie sal begin genereer. Aangesien die generering van dokumentasie nie die grootste behoefte in die ontwikkelingsproses is nie, sal die teiken nie by verstek ingesluit word nie, dit sal eksplisiet uitgevoer moet word.

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

Skrip vir aanlyn sandbox (aanlyn/CMakeLists.txt)

Hier vind ons die derde Python en skep 'n teiken wandbox, wat 'n versoek genereer wat ooreenstem met die diens-API Wandboks, en stuur dit. In reaksie hierop kom 'n skakel na die 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()

projek buite

Kom ons kyk nou hoe om dit alles te gebruik.

vergadering

Die bou van hierdie projek, soos enige ander projek op die CMake-boustelsel, bestaan uit twee fases:

generasie

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

As die opdrag hierbo nie gewerk het nie as gevolg van 'n ouer weergawe van CMake, probeer om dit weg te laat -S:
cmake путь/к/исходникам -B путь/к/сборочной/директории [опции ...]

Meer oor opsies.

Projek bou

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

Meer oor vergadering doelwitte.

Opsies

MYLIB_DEKKING

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

Sluit teiken in coverage, waarmee jy kodedekking met toetse kan begin meet.

MYLIB_TESTING

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

Bied die opsie om eenheidstoetsbou en -teiken af te skakel check. As gevolg hiervan word die meting van kodedekking deur toetse afgeskakel (sien MYLIB_COVERAGE).

Ook, toetsing word outomaties gedeaktiveer as die projek aan 'n ander projek gekoppel is as 'n subprojek deur die opdrag te gebruik add_subdirectory.

MYLIB_DOXYGEN_LANGUAGE

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

Verander die taal van die dokumentasie wat die teiken genereer doc aan die gegewe een. Vir 'n lys van beskikbare tale, sien Doxygen webwerf.

Russies is by verstek geaktiveer.

samestelling teikens

By verstek

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

As die teiken nie gespesifiseer is nie (wat gelykstaande is aan die teiken all), versamel alles wat moontlik is, en roep ook die teiken check.

mylib-eenheid-toetse

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

Stel eenheidstoetse saam. By verstek geaktiveer.

gaan

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

Loop geboude (bou indien nie reeds) eenheidstoetse. By verstek geaktiveer.

Sien ook mylib-unit-tests.

dekking

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

Ontleed lopende (hardloop, indien nog nie) eenheidstoetse vir kodedekking deur toetse met behulp van die program gcovr.

Die dekkingsuitset sal iets soos volg lyk:

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

Die teiken is slegs beskikbaar wanneer die opsie geaktiveer is. MYLIB_COVERAGE.

Sien ook check.

doc

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

Begin die generering van dokumentasie vir die kode deur die stelsel te gebruik Suurstof.

wandboks

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

Die reaksie van die diens lyk ongeveer soos volg:

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

Die diens word hiervoor gebruik. Wandboks. Ek weet nie hoe rubberbedieners hulle het nie, maar ek dink jy moet nie hierdie kenmerk misbruik nie.

voorbeelde

Bou projek in ontfoutingsmodus met dekkingmeting

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

Installering van 'n projek sonder om vooraf te bou en te toets

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

Bou in vrystellingsmodus deur die gegewe samesteller

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

Generering van dokumentasie in Engels

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

Tools

CMaak 3.13

Trouens, CMake weergawe 3.13 word slegs vereis om sommige van die konsole-opdragte wat in hierdie hulp beskryf word, uit te voer. Uit die oogpunt van die sintaksis van CMake-skrifte, is weergawe 3.8 voldoende as die generasie op ander maniere opgeroep word.
Toets biblioteek doktoets

Toetsing kan gedeaktiveer word (sien опцию MYLIB_TESTING).
Suurstof

Om die taal waarin die dokumentasie gegenereer sal word te verander, is daar 'n opsie MYLIB_DOXYGEN_LANGUAGE.
PL tolk Python 3

Vir outomatiese generasie aanlyn sandkaste.

Statiese Analise

Met die hulp van CMake en 'n paar goeie gereedskap, kan jy statiese analise verskaf met minimale vroetel.

Cppcheck

Ondersteuning vir statiese analise-instrument ingebou in CMake Cppcheck.

Om dit te doen, gebruik die opsie CMAKE_CXX_CPPCHECK:

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

Daarna sal statiese analise outomaties elke keer tydens samestelling en hersamestelling van bronne van stapel gestuur word. Niks ekstra hoef gedoen te word nie.

klang

Met 'n wonderlike hulpmiddel scan-build U kan ook statiese ontleding in 'n japtrap uitvoer:

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

Hier, anders as die geval met Cppcheck, is dit nodig om die bou elke keer deur te voer scan-build.

nawoord

CMake is 'n baie kragtige en buigsame stelsel wat jou toelaat om funksionaliteit vir elke smaak en kleur te implementeer. En, hoewel die sintaksis soms veel te wense oorlaat, is die duiwel steeds nie so vreeslik soos hy geskilder is nie. Gebruik die CMake-boustelsel tot voordeel van die samelewing en gesondheid.

→ Laai projek sjabloon af

Bron: will.com

CMake en C++ is broers vir altyd