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

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

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

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

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

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

Съдържание

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_TESTING
      3. MYLIB_DOXYGEN_LANGUAGE
   3. Цели на сборките
      1. По подразбиране
      2. mylib-unit-tests
      3. check
      4. покритие
      5. док
      6. wandbox
   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)

Опции на компилация

Разбира се, ние сме велики програмисти на C++, затова искаме от компилатора максимално ниво на диагностика по време на компилация. Няма да пропусне нито една грешка.

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

Няма да зададем стандарт на езика. Разбира се, най-новият. При това не само включваме стандарта, но и го разпространяваме на тези, които ще използват библиотеката ни. Това се постига чрез задаването на свойството с категория INTERFACE (вж. командата target_compile_features).

target_compile_features(mylib INTERFACE cxx_std_17)

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

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

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)

Намерихме Doxygen.

find_package(Doxygen)

Следващата стъпка е да проверим дали потребителят е задал променлива за езика. Ако е, не я променяме, ако не, взимаме руски. След това конфигурираме файловете на Doxygen. Всички нужни променливи, включително и езика, попадават там по време на конфигурацията (вж. командата configure_file).

След това създаваме цел док, която ще стартира генерирането на документация. Тъй като генерирането на документация не е най-належащата нужда в процеса на разработка, целта по подразбиране няма да бъде активна, ще трябва да я стартираме ръчно.

if (Doxygen_FOUND)
    if (NOT MYLIB_DOXYGEN_LANGUAGE)
        set(MYLIB_DOXYGEN_LANGUAGE Bulgarian)
    endif()
    message(STATUS "Документацията на Doxygen ще бъде генерирана на ${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 на услугата 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 от трета версия")
endif()

Проекта отвън

Сега да разгледаме как да използваме всичко това.

Сборка

Сборката на този проект, както и на всеки друг проект в системата за сборка CMake, се състои от два етапа:

Генерация

cmake -S път\/к\/изходниците -B път\/к\/директорията\/за\/сборка [опции ...]

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

cmake път\/к\/изходниците -B път\/к\/директорията\/за\/сборка [опции ...]

Повече информация за опциите.

Сборка на проекта

cmake --build път\/к\/директорията\/за\/сборка [--target target]

Повече информация за сборните цели.

Опции

MYLIB_COVERAGE

cmake -S ... -B ... -DMYLIB_COVERAGE=ON [други опции ...]

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

MYLIB_TESTING

cmake -S ... -B ... -DMYLIB_TESTING=OFF [други опции ...]

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

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

MYLIB_DOXYGEN_LANGUAGE

cmake -S ... -B ... -DMYLIB_DOXYGEN_LANGUAGE=English [други опции ...]

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

По подразбиране е включен руски.

Цели на сборките

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

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

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

mylib-unit-tests

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

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

check

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.

док

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

Стартира генерация на документация за кода с помощта на системата Doxygen.

wandbox

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

Отговорът от услугата изглежда приблизително така:

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

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

Примери

Сборка на проекта в режим на отстраняване на грешки с измерване на покритието

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

   За смяна на езика, на който ще бъде генерирана документацията, е предвидена опция MYLIB_DOXYGEN_LANGUAGE.

4. Интерпретатор на програмния език Python 3

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

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

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

Cppcheck

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

За това трябва да се използва опция CMAKE_CXX_CPPCHECK:

cmake -S път/към/източниците -B път/към/директорията/за/компилиране -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_CPPCHECK="cppcheck;--enable=all;-Iпът/към/източниците/include"

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

Clang

Чрез чудесния инструмент scan-build може да се стартира статичен анализ за две кратки стъпки:

scan-build cmake -S път/към/източниците -B път/към/директорията/за/компилиране -DCMAKE_BUILD_TYPE=Debug
scan-build cmake --build път/към/директорията/за/компилиране

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

Следсловие

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

→ Свалете шаблона на проекта

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