CMake и C++ са братя завинаги

По време на разработката обичам да сменям компилатори, режими на изграждане, версии на зависимости, извършвам статичен анализ, измервам производителността, събирам покритие, генерирам документация и т.н. И наистина обичам CMake, защото ми позволява да правя каквото искам.

Мнозина се карат на CMake и често заслужено, но ако погледнете, не е толкова лошо, но напоследък никак не е зле, а посоката на развитие е доста положителна.

В тази бележка искам да ви кажа колко лесно е да организирате библиотека със заглавки на C++ в система CMake, за да получите следната функционалност:

1. монтаж;
2. Тестове за автоматично стартиране;
3. Измерване на покритието на кода;
4. инсталация;
5. Автодокументация;
6. Онлайн генериране на пясъчник;
7. Статичен анализ.

Който вече разбира плюсовете и si-make може просто изтегляне на шаблон на проект и започнете да го използвате.

Съдържание

1. Проектирайте отвътре
   1. Структура на проекта
   2. Основен CMake файл (./CMakeLists.txt)
      1. Информация за проекта
      2. Опции на проекта
      3. Опции за компилиране
      4. Основната цел
      5. Инсталация
      6. тестове
      7. Документация
      8. Онлайн пясъчник
   3. Скрипт за тестове (test/CMakeLists.txt)
      1. Тестване
      2. Обхват
   4. Скрипт за документация (doc/CMakeLists.txt)
   5. Скрипт за онлайн пясъчник (online/CMakeLists.txt)
2. проект навън
   1. монтаж
      1. поколение
      2. монтаж
   2. Опции
      1. MYLIB_COVERAGE
      2. MYLIB_ТЕСТВАНЕ
      3. MYLIB_DOXYGEN_LANGUAGE
   3. монтажни цели
      1. По подразбиране
      2. mylib-единични тестове
      3. проверка
      4. обхват
      5. Doc
      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 скриптове, така че те ще бъдат анализирани подробно. Останалите файлове могат да се разглеждат директно от всеки. на страницата на шаблонния проект.

Основен CMake файл (./CMakeLists.txt)

Информация за проекта

На първо място, трябва да заявите желаната версия на системата CMake. CMake се развива, сигнатурите на командите се променят, поведението при различни условия. За да може CMake веднага да разбере какво искаме от него, трябва незабавно да коригираме изискванията си към него.

cmake_minimum_required(VERSION 3.13)

След това обозначаваме нашия проект, неговото име, версия, използвани езици и т.н. команду project).

В този случай посочваме езика CXX (което означава C++), така че CMake да не си прави труда да търси C компилатор (по подразбиране в CMake са включени два езика: C и C++).

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
)

Ние също така ще деактивираме разширенията, за да отговаряме напълно на езиковия стандарт C ++. Те са активирани по подразбиране в CMake.

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

Основната цел

Нашата библиотека се състои само от заглавни файлове, което означава, че нямаме изчерпване под формата на статични или динамични библиотеки. От друга страна, за да използвате нашата библиотека външно, тя трябва да бъде инсталирана, трябва да бъде откриваема в системата и свързана с вашия проект, и в същото време същите тези хедъри, както и евентуално някои допълнителни, са прикрепени към него имоти.

За тази цел създаваме интерфейсна библиотека.

add_library(mylib INTERFACE)

Ние свързваме заглавките с нашата интерфейсна библиотека.

Модерна, модерна, младежка употреба на CMake означава, че заглавките, свойствата и т.н. предавани през една цел. Така че е достатъчно да се каже target_link_libraries(target PRIVATE dependency)и всички заглавки, които са свързани с целта dependency, ще бъдат достъпни за източници, принадлежащи към целта target. И нямате нужда от никакви [target_]include_directories. Това ще бъде демонстрирано по-долу при анализиране CMake скрипт за модулни тестове.

Струва си да се обърне внимание и на т.нар. выражения-генераторы: $<...>.

Тази команда асоциира заглавките, от които се нуждаем, с нашата интерфейсна библиотека и ако нашата библиотека е свързана с която и да е цел в рамките на същата CMake йерархия, тогава заглавките от директорията ще бъдат свързани с нея ${CMAKE_CURRENT_SOURCE_DIR}/includeи ако нашата библиотека е инсталирана в системата и свързана с друг проект с помощта на командата find_package, тогава заглавките от директорията ще бъдат свързани с него include спрямо инсталационната директория.

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

Да зададем езиков стандарт. Разбира се, последният. В същото време ние не само включваме стандарта, но и го разширяваме до тези, които ще използват нашата библиотека. Това се постига благодарение на факта, че зададеното свойство има категория INTERFACE (Cm. команда target_compile_features).

target_compile_features(mylib INTERFACE cxx_std_17)

Получаваме псевдоним за нашата библиотека. И за красота ще бъде в специално "namespace". Това ще бъде полезно, когато в нашата библиотека се появят различни модули и ние ги свързваме независимо един от друг. Като в Буста например.

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, CMake автоматично ще генерира грешка. Тоест, няма да е необходимо да следите версиите ръчно.

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)

тестове

Ако тестовете са изрично деактивирани с съответна опция или нашият проект е подпроект, тоест той е свързан с друг проект на 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()

Скрипт за тестове (test/CMakeLists.txt)

Тестване

Първо, намираме пакет с желаната тестова рамка (заменете я с любимата).

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)

Ние свързваме зависимости. Моля, имайте предвид, че прикачихме само целите на CMake, от които се нуждаехме, към нашия двоичен файл и не извикахме командата target_include_directories. Заглавки от тестовата рамка и от нашия Mylib::mylib, както и опции за компилация (в нашия случай езиковият стандарт C++), обходени заедно с тези цели.

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

Накрая създаваме фиктивна цел, чиято „компилация“ е еквивалентна на провеждане на тестове, и добавяме тази цел към компилацията по подразбиране (това е отговорност на атрибута ALL). Това означава, че компилацията по подразбиране ще задейства изпълнението на тестовете, което означава, че никога няма да забравим да ги изпълним.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Обхват

След това активираме измерване на покритието на кода, ако е указана подходящата опция. Няма да навлизам в подробности, защото те се отнасят повече до инструмент за измерване на покритието, отколкото до CMake. Важно е само да се отбележи, че на базата на резултатите ще бъде създаден гол 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()

Скрипт за документация (doc/CMakeLists.txt)

Намерих Доксиген.

find_package(Doxygen)

След това проверяваме дали променливата с езика е зададена от потребителя. Ако да, тогава не го докосваме, ако не, тогава вземаме руски. След това конфигурираме системните файлове на 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 ()

Скрипт за онлайн пясъчник (online/CMakeLists.txt)

Тук намираме третия Python и създаваме цел wandbox, който генерира заявка, съответстваща на API на услугата Кутия за пръчици, и го изпраща. В отговор идва връзка към готовата пясъчна кутия.

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, се състои от два етапа:

поколение

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

Ако командата по-горе не работи поради по-стара версия на CMake, опитайте да пропуснете -S:

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

Повече за опциите.

Изграждане на проект

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

Повече за монтажните цели.

Опции

MYLIB_COVERAGE

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

Включва цел coverage, с който можете да започнете да измервате покритието на кода с тестове.

MYLIB_ТЕСТВАНЕ

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

Осигурява възможност за деактивиране на компилация и цел за тест на единица check. В резултат на това измерването на покритието на кода чрез тестове е изключено (вижте MYLIB_COVERAGE).

Освен това тестването се деактивира автоматично, ако проектът е свързан с друг проект като подпроект с помощта на командата add_subdirectory.

MYLIB_DOXYGEN_LANGUAGE

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

Превключва езика на документацията, която целта генерира doc към дадения. За списък с наличните езици вж Уебсайт на Doxygen.

Руският е активиран по подразбиране.

монтажни цели

По подразбиране

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

Ако целта не е посочена (което е еквивалентно на целта all), събира всичко, което е възможно, и също така се обажда на целта check.

mylib-единични тестове

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

Компилира модулни тестове. Активирано по подразбиране.

проверка

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

Изпълнява събраните (събрани, ако вече не са) модулни тестове. Активирано по подразбиране.

Вижте също mylib-unit-tests.

обхват

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

Анализира изпълнявани (извършва, ако вече не) модулни тестове за покритие на кода от тестове, използващи програмата gcovr.

Изпускателната тръба на покритието ще изглежда по следния начин:

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

Doc

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. CMake 3.13

   Всъщност CMake версия 3.13 е необходима само за изпълнение на някои от конзолните команди, описани в тази помощ. От гледна точка на синтаксиса на CMake скриптовете, версия 3.8 е достатъчна, ако генерирането се извиква по други начини.

2. Библиотека за тестване doctest

   Тестването може да бъде деактивирано (вижте опцию MYLIB_TESTING).

3. Кислород

   Има опция за превключване на езика, на който ще се генерира документацията MYLIB_DOXYGEN_LANGUAGE.

4. PL преводач Python 3

   За автоматично генериране онлайн пясъчници.

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

С помощта на CMake и няколко добри инструмента можете да предоставите статичен анализ с минимално бъркане.

Cppcheck

Поддръжка за инструмент за статичен анализ, вграден в CMake Cppcheck.

За да направите това, използвайте опцията 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 путь/к/сборочной/директории

Тук, за разлика от случая с Cppcheck, се изисква компилацията да се изпълнява всеки път scan-build.

послеслов

CMake е много мощна и гъвкава система, която ви позволява да реализирате функционалност за всеки вкус и цвят. И въпреки че синтаксисът понякога оставя много да се желае, дяволът все още не е толкова страшен, колкото е нарисуван. Използвайте системата за изграждане на CMake в полза на обществото и здравето.

→ Изтеглете шаблон на проект

Източник: www.habr.com