ЦМаке и Ц++ су заувек браћа

Током развоја, волим да мењам компајлере, начине градње, верзије зависности, вршим статичку анализу, мерим перформансе, прикупљам покривеност, генеришем документацију итд. И заиста волим ЦМаке јер ми омогућава да радим све што желим.

Многи људи критикују ЦМаке, и то често заслужено, али ако погледате, није све тако лоше, а недавно уопште није лоше, а правац развоја је прилично позитиван.

У овој напомени желим да вам кажем како да једноставно организујете библиотеку заглавља у Ц++ у систему ЦМаке да бисте добили следећу функционалност:

1. Скупштина;
2. Тестови за аутоматско покретање;
3. Мерење покривености кода;
4. Инсталлатион;
5. Ауто-документација;
6. Генерисање онлајн сандбок-а;
7. Статичка анализа.

Свако ко већ разуме предности и Ц-маке може једноставно преузмите шаблон пројекта и почните да га користите.

Садржина

1. Пројекат изнутра
   1. Структура пројекта
   2. Главна ЦМаке датотека (./ЦМакеЛистс.ткт)
      1. Информације о пројекту
      2. Опције пројекта
      3. Опције компилације
      4. Главни циљ
      5. Инсталација
      6. Тестови
      7. Записи
      8. Онлине сандбок
   3. Тест скрипта (тест/ЦМакеЛистс.ткт)
      1. Тестирање
      2. Покривеност
   4. Скрипта за документацију (доц/ЦМакеЛистс.ткт)
   5. Скрипта за онлајн сандбок (онлине/ЦМакеЛистс.ткт)
2. Пројекат споља
   1. Скупштина
      1. Генерација
      2. Скупштина
   2. Опције
      1. МИЛИБ_ЦОВЕРАГЕ
      2. МИЛИБ_ТЕСТИНГ
      3. МИЛИБ_ДОКСИГЕН_ЛАНГУАГЕ
   3. Скупштински циљеви
      1. Подразумевано
      2. милиб-унит-тестс
      3. проверити
      4. Покривеност
      5. доктор
      6. кутија за штапиће
   4. Примери
3. Алат
4. Статичка анализа
5. Афтерворд

Пројекат изнутра

Структура пројекта

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

Углавном ћемо причати о томе како организовати ЦМаке скрипте, тако да ће се о њима детаљно разговарати. Свако може директно да види остале датотеке на страници пројекта шаблона.

Главна ЦМаке датотека (./ЦМакеЛистс.ткт)

Информације о пројекту

Пре свега, потребно је да затражите потребну верзију ЦМаке система. ЦМаке се развија, потписи команди и понашање у различитим условима се мењају. Да би ЦМаке одмах разумео шта желимо од њега, морамо одмах да забележимо своје захтеве за њега.

cmake_minimum_required(VERSION 3.13)

Затим ћемо означити наш пројекат, његово име, верзију, језике који се користе итд. (види. команду project).

У овом случају означавамо језик CXX (а то значи Ц++) тако да ЦМаке не напреже и не тражи компајлер језика Ц (подразумевано, ЦМаке укључује два језика: Ц и Ц++).

project(Mylib VERSION 1.0 LANGUAGES CXX)

Овде можете одмах проверити да ли је наш пројекат укључен у неки други пројекат као потпројекат. Ово ће много помоћи у будућности.

get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Опције пројекта

Ми ћемо понудити две опције.

Прва опција је MYLIB_TESTING — да онемогућите тестове јединица. Ово може бити неопходно ако смо сигурни да је све у реду са тестовима, али желимо само, на пример, да инсталирамо или пакујемо наш пројекат. Или је наш пројекат укључен као потпројекат - у овом случају, корисник нашег пројекта није заинтересован за покретање наших тестова. Не тестирате зависности које користите, зар не?

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

Поред тога, направићемо посебну опцију MYLIB_COVERAGE за мерење покривености кода тестовима, али ће захтевати додатне алате, тако да ће морати да буде експлицитно омогућен.

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

Опције компилације

Наравно, ми смо цоол плус програмери, тако да желимо максималан ниво дијагностике времена компајлирања од компајлера. Ни један миш се неће провући.

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
)

Такође ћемо онемогућити екстензије како бисмо у потпуности били у складу са стандардом језика Ц++. Они су подразумевано омогућени у ЦМаке-у.

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

Главни циљ

Наша библиотека се састоји само од датотека заглавља, што значи да немамо никакав исцрпак у облику статичких или динамичких библиотека. С друге стране, да би нашу библиотеку користили екстерно, потребно је да она буде инсталирана, да буде детектива у систему и повезана са вашим пројектом, а у исто време ова иста заглавља, као и евентуално нека додатна, су јој придружена својства.

У ту сврху креирамо библиотеку интерфејса.

add_library(mylib INTERFACE)

Повезујемо заглавља са нашом библиотеком интерфејса.

Модерна, модерна, омладинска употреба ЦМаке-а подразумева да заглавља, својства итд. преноси преко једне једине мете. Дакле, довољно је рећи target_link_libraries(target PRIVATE dependency), и сва заглавља која су повезана са циљем dependency, биће доступан за изворе који припадају циљу target. И не треба ти [target_]include_directories. Ово ће бити показано у наставку анализе ЦМаке скрипта за јединичне тестове.

Такође вреди обратити пажњу на тзв. выражения-генераторы: $<...>.

Ова команда повезује заглавља која су нам потребна са нашом библиотеком интерфејса, и ако је наша библиотека повезана са било којим циљем унутар исте ЦМаке хијерархије, онда ће заглавља из директоријума бити повезана са њом ${CMAKE_CURRENT_SOURCE_DIR}/include, и ако је наша библиотека инсталирана на систему и повезана са другим пројектом помоћу команде find_package, онда ће заглавља из директоријума бити повезана са њим include у односу на инсталациони директоријум.

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

Хајде да поставимо језички стандард. Наравно, последњи. Истовремено, не само да укључујемо стандард, већ га проширујемо и на оне који ће користити нашу библиотеку. Ово се постиже чињеницом да постављено својство има категорију INTERFACE (Види. наредба таргет_цомпиле_феатурес).

target_compile_features(mylib INTERFACE cxx_std_17)

Хајде да направимо алиас за нашу библиотеку. Штавише, због лепоте, биће у посебном „именском простору“. Ово ће бити корисно када се у нашој библиотеци појаве различити модули, а ми идемо да их повежемо независно један од другог. Као у Бусти, на пример.

add_library(Mylib::mylib ALIAS mylib)

Инсталација

Инсталирање наших заглавља у систем. Овде је све једноставно. Кажемо да фасцикла са свим заглављима треба да иде у директоријум include у односу на локацију инсталације.

install(DIRECTORY include/mylib DESTINATION include)

Затим обавештавамо систем изградње да желимо да можемо да позовемо команду у пројектима треће стране find_package(Mylib) и добити гол Mylib::mylib.

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

Следећу чаролију треба схватити на овај начин. Када у пројекту треће стране позивамо команду find_package(Mylib 1.2.3 REQUIRED), а права верзија инсталиране библиотеке неће бити компатибилна са верзијом 1.2.3ЦМаке ће аутоматски генерисати грешку. То јест, нећете морати ручно да пратите верзије.

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)

Тестови

Ако су тестови експлицитно онемогућени помоћу одговарајућа опција или је наш пројекат потпројекат, односно повезан је са другим ЦМаке пројектом помоћу команде add_subdirectory, не идемо даље по хијерархији, а скрипта, која описује команде за генерисање и покретање тестова, једноставно не ради.

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

Записи

Документација се такође неће генерисати у случају потпројекта.

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

Онлине сандбок

Исто тако, потпројекат неће имати ни онлајн сандбок.

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

Тест скрипта (тест/ЦМакеЛистс.ткт)

Тестирање

Пре свега, налазимо пакет са потребним оквиром за тестирање (замените својим омиљеним).

find_package(doctest 2.3.3 REQUIRED)

Хајде да направимо нашу извршну датотеку са тестовима. Обично додајем директно у извршну бинарну датотеку само датотеку која ће садржати функцију main.

add_executable(mylib-unit-tests test_main.cpp)

И додајем датотеке у којима су сами тестови описани касније. Али не морате то да радите.

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

Повезујемо зависности. Имајте на уму да смо повезали само ЦМаке циљеве који су нам били потребни са нашом бинарном датотеком и нисмо позвали команду target_include_directories. Наслови из оквира за тестирање и из нашег Mylib::mylib, као и параметри изградње (у нашем случају, ово је стандард језика Ц++) дошли су заједно са овим циљевима.

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

Коначно, креирамо лажни циљ, чија је „градња“ еквивалентна покретању тестова, и додајемо овај циљ подразумеваној верзији (атрибут је одговоран за ово ALL). То значи да подразумевана израда покреће тестове за покретање, што значи да никада нећемо заборавити да их покренемо.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Покривеност

Затим омогућавамо мерење покривености кода ако је наведена одговарајућа опција. Нећу улазити у детаље, јер се они више односе на алат за мерење покривености него на ЦМаке. Важно је само напоменути да ће се на основу резултата креирати циљ coverage, са којим је згодно започети мерење покривености.

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

Скрипта за документацију (доц/ЦМакеЛистс.ткт)

Фоунд Докиген.

find_package(Doxygen)

Затим проверавамо да ли је корисник подесио променљиву језика. Ако јесте, онда га не дирамо, ако не, онда узимамо руски. Затим конфигуришемо системске датотеке Докиген. Све потребне варијабле, укључујући језик, иду тамо током процеса конфигурације (види. команду configure_file).

Затим стварамо циљ doc, који ће почети са генерисањем документације. Пошто генерисање документације није највећа потреба у процесу развоја, циљ неће бити подразумевано омогућен, већ ће се морати експлицитно покренути.

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

Скрипта за онлајн сандбок (онлине/ЦМакеЛистс.ткт)

Овде налазимо трећи Питхон и креирамо мету wandbox, који генерише захтев који одговара АПИ-ју услуге Вандбок, и испраћа га. Одговор долази са везом до готовог сандбок-а.

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

Пројекат споља

Погледајмо сада како све ово искористити.

Скупштина

Изградња овог пројекта, као и било ког другог пројекта на ЦМаке буилд систему, састоји се од две фазе:

Генерација

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

Ако горња команда није радила због старе верзије ЦМаке-а, покушајте да изоставите -S:

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

Више о опцијама.

Изградња пројекта

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

Више о скупштинским циљевима.

Опције

МИЛИБ_ЦОВЕРАГЕ

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

Укључује мету coverage, са којим можете почети да мерите покривеност кода тестовима.

МИЛИБ_ТЕСТИНГ

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

Пружа могућност онемогућавања изградње и циљања јединичних тестова check. Као резултат, мерење покривености кода тестовима је искључено (види. MYLIB_COVERAGE).

Тестирање је такође аутоматски онемогућено ако је пројекат повезан са другим пројектом као потпројекат помоћу команде add_subdirectory.

МИЛИБ_ДОКСИГЕН_ЛАНГУАГЕ

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

Мења језик документације коју циљ генерише doc датом. За листу доступних језика, погледајте Веб страница система Докиген.

Руски је подразумевано омогућен.

Скупштински циљеви

Подразумевано

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

Ако циљ није наведен (што је еквивалентно циљу all), прикупља све што може, а такође позива мету check.

милиб-унит-тестс

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

Саставља јединичне тестове. Омогућено подразумевано.

проверити

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

Покреће прикупљене (сакупљене, ако већ нису) тестове јединица. Омогућено подразумевано.

Види такође mylib-unit-tests.

Покривеност

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

Анализира покренуте (покреће, ако већ не) тестове јединица за покривеност кода тестовима помоћу програма гцовр.

Издувни слој премаза ће изгледати отприлике овако:

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

Циљ је доступан само када је опција омогућена MYLIB_COVERAGE.

Види такође check.

доктор

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

Започиње генерисање кодне документације користећи систем Докиген.

кутија за штапиће

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

Одговор сервиса изгледа отприлике овако:

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

За ово се користи услуга Вандбок. Не знам колико су њихови сервери флексибилни, али мислим да ову прилику не треба злоупотребљавати.

Примери

Изградите пројекат у режиму за отклањање грешака са мерењем покривености

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

Инсталирање пројекта без претходне монтаже и тестирања

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

Изградите у режиму издања са датим компајлером

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

Генерисање документације на енглеском језику

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

Алат

1. ЦМаке 3.13

   У ствари, ЦМаке верзија 3.13 је потребна само за покретање неких од команди конзоле описаних у овој помоћи. Са становишта синтаксе ЦМаке скрипти, верзија 3.8 је довољна ако се генерисање позива на друге начине.

2. Библиотека за тестирање доцтест

   Тестирање се може онемогућити (погледајте опцию MYLIB_TESTING).

3. Докиген

   Да бисте променили језик на коме ће се генерисати документација, постоји опција MYLIB_DOXYGEN_LANGUAGE.

4. Преводилац језика питхон КСНУМКС

   За аутоматско генерисање онлајн сандбокови.

Статичка анализа

Са ЦМаке-ом и неколико добрих алата, можете пружити статичку анализу уз минималан напор.

Цппцхецк

ЦМаке има уграђену подршку за алат за статичку анализу Цппцхецк.

Да бисте то урадили, потребно је да користите опцију CMAKE_CXX_CPPCHECK:

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

Након овога, статичка анализа ће се аутоматски покренути сваки пут када се извор преведе и поново компајлира. Нема потребе да се ради ништа додатно.

Цланг

Уз помоћ дивног алата scan-build Такође можете да покренете статичку анализу за кратко време:

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

Овде, за разлику од случаја са Цппцхецк-ом, морате сваки пут да покренете буилд scan-build.

Афтерворд

ЦМаке је веома моћан и флексибилан систем који вам омогућава да имплементирате функционалност за сваки укус и боју. И, иако синтакса понекад оставља много да се пожели, ђаво ипак није тако страшан као што је насликан. Користите систем изградње ЦМаке за добробит друштва и здравља.

→ Преузмите шаблон пројекта

Извор: ввв.хабр.цом