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

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

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

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

Компилация;
Автоматично стартиране на тестове;
Измерване на покритие на кода;
Инсталация;
Автодокументиране;
Генериране на онлайн пясъчник;
Статичен анализ.

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

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

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

.
├── 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 не се тества в режим на подмодул")
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).

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

if (Doxygen_FOUND)
    if (NOT MYLIB_DOXYGEN_LANGUAGE)
        set(MYLIB_DOXYGEN_LANGUAGE Russian)
    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, и я изпраща. В отговор получаваме връзка към готова пес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 "За създаването на онлайн песSandbox е необходим интерпретатор на Python версия 3")
endif()

Проект отвън

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

Сглобяване

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

Генериране

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

Ако горната команда не сработи поради стара версия на CMake, опитайте да пропуснете -S:
cmake път/к/изходниците -B път/к/сборочната/директория [опции ...]

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

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

cmake --build път/к/сборочната/директория [--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 [други опции ...]

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

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

Цели за компилиране

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

cmake --build път/към/директория/за/сборка
cmake --build път/към/директория/за/сборка --target all

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

mylib-unit-tests

cmake --build път/към/директория/за/сборка --target mylib-unit-tests

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

check

cmake --build път/към/директория/за/сборка --target check

Стартира събраните (или компилира, ако все още не са) модулни тестове. Включено е по подразбиране.

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

покритие

cmake --build път/към/директория/за/сборка --target coverage

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

Изходът от покритие ще изглежда приблизително така:

------------------------------------------------------------------------------
                           Доклад за покритие на кода от GCC
Директория: /път/към/cmakecpptemplate/include/
------------------------------------------------------------------------------
Файл                                       Линии    Изпълнени  Покритие   Липсващи
------------------------------------------------------------------------------
mylib/myfeature.hpp                            2       2   100%   
------------------------------------------------------------------------------
TOTAL                                          2       2   100%
------------------------------------------------------------------------------

Целта е налична само когато опцията е включена MYLIB_COVERAGE.

Вижте също check.

doc

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

Инструменти

CMake 3.13
Всъщност версията на CMake 3.13 е необходима само за изпълнение на някои от командите в конзолата, описани в това ръководство. От гледна точка на синтаксиса на CMake скриптовете, достатъчна е версия 3.8, ако генерирането се извиква по други начини.
Библиотека за тестване doctest
Тестването може да бъде деактивирано (виж. опцията MYLIB_TESTING).
Doxygen
За смяна на езика, на който ще бъде генерирана документацията, е предвидена опция MYLIB_DOXYGEN_LANGUAGE.
Интерпретатор на ЯП Python 3
За автоматично генериране онлайн песенци.

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

С 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