🥇CMake og C++ — brødre for altid

Under development, I love to change compilers, build modes, dependency versions, perform static analysis, measure performance, gather coverage, generate documentation, etc. I really love CMake because it allows me to do everything I want.

Many criticize CMake, often justifiably, but if you look closely, it's not that bad, and lately it's actually quite good, and the direction of development is quite positive.

In this note, I want to explain how relatively easily to organize a header library in C++ using CMake, to achieve the following functionality:

Building;
Auto-launching tests;
Measuring code coverage;
Installation;
Auto-documentation;
Generating an online sandbox;
Static analysis.

Anyone already familiar with C++ and CMake can simply download the project template and start using it.

The project from the inside

Project structure

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

The main focus will be on how to structure CMake scripts, so they will be examined in detail. Other files can be reviewed directly on the project template page..

Main CMake file (./CMakeLists.txt)

Information om projektet

First, you need to request the required version of CMake. CMake evolves, command signatures change, behavior under various conditions varies. To ensure CMake immediately understands our requirements, we need to specify them upfront.

cmake_minimum_required(VERSION 3.13)

Then we will define our project, its name, version, languages used, and others (see the project command).

In this case, we specify the language CXX (which means C++), so CMake doesn’t get confused and look for a C language compiler (by default, CMake includes two languages: C and C++).

project(Mylib VERSION 1.0 LANGUAGES CXX)

Her kan du straks tjekke, om vores projekt er inkluderet som et underprojekt i et andet projekt. Det vil hjælpe betydeligt fremadrettet.

get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Project options

Lad os overveje to muligheder.

Den første mulighed — MYLIB_TESTING — til at deaktivere modultests. Dette kan være nødvendigt, hvis vi er sikre på, at alt er i orden med testene, og vi f.eks. kun ønsker at installere eller pakke vores projekt. Eller hvis vores projekt er inkluderet som et underprojekt — i det tilfælde ville brugeren af vores projekt ikke være interesseret i at køre vores tests. Tester du ikke de afhængigheder, du bruger?

option(MYLIB_TESTING "Aktivér modulær testning" ON)

Derudover vil vi lave en separat mulighed MYLIB_COVERAGE for måling af testdækning, men den vil kræve yderligere værktøjer, så den skal aktiveres eksplicit.

option(MYLIB_COVERAGE "Aktivér måling af testdækning" OFF)

Compilation options

Selvfølgelig er vi dygtige C++ programmører, så vi ønsker maksimum diagnostiske niveauer fra compileren. Ingen mus skal kunne slippe forbi.

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
)

Vi deaktiverer også udvidelserne for helt at overholde C++ sprogets standard. Som standard er de aktiveret i CMake.

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

Main target

Vores bibliotek består kun af header-filer, så vi har ingen output i form af statiske eller dynamiske biblioteker. På den anden side, for at bruge vores bibliotek udenfor, skal det installeres, så det kan findes i systemet og links til dit projekt, og samtidig skal disse header-filer være bundet til det, samt muligvis nogle yderligere egenskaber.

Til dette formål opretter vi et interface-bibliotek.

add_library(mylib INTERFACE)

Vi binder headers til vores interface-bibliotek.

Moderne, trendy, ungdommelig brug af CMake indebærer, at headers, egenskaber osv. overføres gennem et enkelt mål. Så det er nok at sige target_link_libraries(target PRIVATE dependency), og alle headers, der er associeret med målet dependency, vil være tilgængelige for kildene, der tilhører målet target. Og der kræves ingen [target_]include_directoriesDette vil blive vist nedenfor i analysen CMake-scriptet til modulære tests.

Det er også værd at bemærke det såkaldte genereringsudtryk: $.

Denne kommando forbinder de nødvendige headers med vores interface-bibliotek, og hvis vores bibliotek bliver tilsluttet et mål i en CMake-hierarki, vil headers fra mappen ${CMAKE_CURRENT_SOURCE_DIR}/include, blive knyttet til det, og hvis vores bibliotek er installeret i systemet og tilsluttet i et andet projekt med kommandoen find_package, vil headers fra mappen include i forhold til installationsmappen.

target_include_directories(mylib INTERFACE
    $
    $
)

Lad os fastsætte sprogstandarden. Selvfølgelig den seneste. Ikke bare inkluderer vi standarden, men spreder den til dem, der vil bruge vores bibliotek. Dette opnås ved, at den installerede egenskab har kategorien INTERFACE (se kommandoen target_compile_features).

target_compile_features(mylib INTERFACE cxx_std_17)

Lad os oprette et alias for vores bibliotek. For æstetikens skyld vil det være i et særligt "navnerum". Dette vil være nyttigt, når vores bibliotek får forskellige moduler, og vi vil tilslutte dem uafhængigt af hinanden. Som i Boost, for eksempel.

add_library(Mylib::mylib ALIAS mylib)

Installation

Installation af vores headers i systemet. Her er det simpelt. Vi siger, at mappen med alle headers skal placeres i mappen include i forhold til installationsstedet.

install(DIRECTORY include/mylib DESTINATION include)

Dernæst informerer vi bygningssystemet om, at vi ønsker at kunne kalde kommandoen find_package(Mylib) og få målet Mylib::mylib.

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

Den næste kommando skal forstås således. Når vi i et eksternt projekt kalder kommandoen find_package(Mylib 1.2.3 REQUIRED), og den faktiske version af det installerede bibliotek er inkompatibel med versionen 1.2.3, vil CMake automatisk generere en fejl. Det vil sige, at vi ikke behøver at holde øje med versionerne manuelt.

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)

Tests

Hvis testene er blevet deaktiveret klart med den relevante indstilling eller vores projekt er et underprojekt, hvilket betyder, at det er tilsluttet et andet CMake-projekt via kommandoen add_subdirectory, vi går ikke videre i hierarkiet, og scriptet, der beskriver kommandoerne til at generere og køre tests, bliver simpelthen ikke kørt.

if(NOT MYLIB_TESTING)
    message(STATUS "Testning af Mylib projekt er deaktiveret")
elseif(IS_SUBPROJECT)
    message(STATUS "Mylib testes ikke i undermodulet")
else()
    add_subdirectory(test)
endif()

Dokumentation

Dokumentationen vil heller ikke blive genereret i tilfælde af et underprojekt.

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

Online sandbox

Tilsvarende vil der heller ikke være en online sandkasse for underprojektet.

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

Script for tests (test/CMakeLists.txt)

Testning

Først finder vi pakken med det nødvendige testframework (udskift med dit yndlings).

find_package(doctest 2.3.3 REQUIRED)

Vi opretter vores eksekverbare fil med tests. Normalt tilføjer jeg kun filen, der indeholder funktionen, direkte i den eksekverbare binær. main.

add_executable(mylib-unit-tests test_main.cpp)

Men jeg tilføjer testfilerne senere. Men dette er ikke nødvendigt.

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

Vi tilslutter afhængigheder. Bemærk, at vi kun har knyttet de nødvendige CMake-mål til vores binær, og vi kaldte ikke kommandoen target_include_directories. Headerne fra testframeworket og fra vores Mylib::mylib, samt byggeparametre (i vores tilfælde er det standarden for C++) kom igennem med disse mål.

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

Endelig opretter vi et fiktivt mål, hvis "bygning" er lig med at køre tests, og tilføjer dette mål til standardbygningen (dette håndteres af attributten ALL). Dette betyder, at standardbygningen initierer testen, så vi aldrig glemmer at køre dem.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Coverage

Derefter aktiverer vi kodeoverdækning, hvis den tilsvarende mulighed er angivet. Jeg vil ikke gå ind i detaljerne, da de mere relaterer til værktøjet til at måle dækning end til CMake. Det er kun vigtigt at bemærke, at der ud fra resultaterne vil blive oprettet et mål coverage, som praktisk kan bruges til at udføre dækning.

find_program(GCOVR_EXECUTABLE gcovr)
if(MYLIB_COVERAGE AND GCOVR_EXECUTABLE)
    message(STATUS "Måling af testdækning er aktiveret")

    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 "Programmet gcovr er nødvendigt for at måle testdækning")
endif()

Script for documentation (doc/CMakeLists.txt)

Vi har fundet Doxygen.

find_package(Doxygen)

Dernæst tjekker vi, om brugeren har angivet en sprogvariabel. Hvis ja, rører vi ikke ved den; hvis nej, tager vi russisk. Derefter konfigurerer vi Doxygen-systemfilerne. Alle nødvendige variabler, inklusive sproget, kommer ind i konfigurationen (se. configure_file-kommanden).

Derefter opretter vi et mål doc, der vil starte genereringen af dokumentationen. Da dokumentationsgenerering ikke er den største nødvendighed i udviklingsprocessen, vil målet som standard ikke være aktiveret, det skal startes eksplicit.

if (Doxygen_FOUND)
    if (NOT MYLIB_DOXYGEN_LANGUAGE)
        set(MYLIB_DOXYGEN_LANGUAGE Dansk)
    endif()
    message(STATUS "Doxygen-dokumentation vil blive genereret på ${MYLIB_DOXYGEN_LANGUAGE}")
    configure_file(Doxyfile.in Doxyfile)
    add_custom_target(doc COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}\/Doxyfile)
endif ()

Script for online sandbox (online/CMakeLists.txt)

Her finder vi den tredje Python og opretter et mål wandbox, der genererer en forespørgsel, der svarer til API'en for tjenesten Wandbox, og sender den. I svaret modtager vi et link til den færdige sandkasse.

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 "En Python 3 fortolker er nødvendig for at oprette en online sandkasse.")
endif()

The project from the outside

Nu ser vi på, hvordan man bruger det hele.

Kompilering

Bygningen af dette projekt, ligesom ethvert andet projekt i CMake-bygsystemet, består af to trin:

Generation

cmake -S sti\/til\/kilde -B sti\/til\/bygge\/mappe [muligheder ...]

Hvis ovenstående kommando ikke virker på grund af en ældre version af CMake, kan du prøve at droppe -S:
cmake sti\/til\/kilde -B sti\/til\/bygge\/mappe [muligheder ...]

Læs mere om mulighederne.

Byg projektet

cmake --build sti\/til\/bygge\/mappe [--target target]

Læs mere om bygge-mål.

Muligheder

MYLIB_COVERAGE

cmake -S ... -B ... -DMYLIB_COVERAGE=ON [andre muligheder ...]

Aktiverer målet coverage, ved hjælp af hvilken man kan starte en måling af kode dækning med tests.

MYLIB_TESTING

cmake -S ... -B ... -DMYLIB_TESTING=OFF [andre muligheder ...]

Giver mulighed for at deaktivere byggeriet af modul tests og mål check. Følgelig deaktiveres måling af kode dækning med tests (se. MYLIB_COVERAGE).

Også testning deaktiveres automatisk, hvis projektet inkluderes i et andet projekt som et underprojekt ved hjælp af kommandoen add_subdirectory.

MYLIB_DOXYGEN_LANGUAGE

cmake -S ... -B ... -DMYLIB_DOXYGEN_LANGUAGE=English [andre muligheder ...]

Skifter sprog for dokumentationen, som målet genererer doc til det angivne. Se listen over tilgængelige sprog på Doxygen systemets hjemmeside.

Som standard er russisk aktiveret.

Build targets

By default

cmake --build sti/til/bygningsdirectory
cmake --build sti/til/bygningsdirectory --target all

Hvis målet ikke er angivet (hvilket er ækvivalent med målet alle), bygger alt, hvad der kan, samt kalder målet check.

mylib-unit-tests

cmake --build sti/til/bygningsdirectory --target mylib-unit-tests

Kompilerer modul tests. Aktiveret som standard.

check

cmake --build sti/til/bygningsdirectory --target check

Kører de bygget (bygger, hvis ikke allerede) modul tests. Aktiveret som standard.

Se også mylib-unit-tests.

coverage

cmake --build sti/til/bygningsdirectory --target coverage

Analyserer de kørende (kører, hvis ikke allerede) modul tests for kode dækning ved hjælp af programmet gcovr.

Udgangen af dækningen vil se omtrent sådan ud:

------------------------------------------------------------------------------
                           GCC Code Coverage Report
Directory: /sti/til/cmakecpptemplate/include/
------------------------------------------------------------------------------
Filer                                       Linjer    Exec  Dækning   Manglende
------------------------------------------------------------------------------
mylib/myfeature.hpp                            2       2   100%   
------------------------------------------------------------------------------
TOTAL                                          2       2   100%
------------------------------------------------------------------------------

Målet er kun tilgængeligt, når mulighederne er aktiveret MYLIB_COVERAGE.

Se også check.

doc

cmake --build sti/til/bygningsdirectory --target doc

Starter genereringen af dokumentation til koden ved hjælp af systemet Doxygen.

wandbox

cmake --build sti/til/bygningsdirectory --target wandbox

Svaret fra tjenesten ser omtrent sådan ud:

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

Dette gøres ved hjælp af tjenesten Wandbox. Jeg ved ikke, hvor elastiske deres servere er, men jeg tror, at man ikke bør misbruge denne mulighed.

Eksempler

Bygning af projektet i debug-tilstand med måling af dækning

cmake -S sti/til/kilde -B sti/til/bygningsdirectory -DCMAKE_BUILD_TYPE=Debug -DMYLIB_COVERAGE=ON
cmake --build sti/til/bygningsdirectory --target coverage --parallel 16

Installation af projektet uden forudgående opbygning og testning

cmake -S sti/til/kilde -B sti/til/bygningsmappe -DMYLIB_TESTING=OFF -DCMAKE_INSTALL_PREFIX=sti/til/installationsmappe
cmake --build sti/til/bygningsmappe --target install

Bygning i udgivelsesmåde med den angivne compiler

cmake -S sti/til/kilde -B sti/til/bygningsmappe -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-8 -DCMAKE_PREFIX_PATH=sti/til/directory/hvor/afhængigheder/er/installeret
cmake --build sti/til/bygningsmappe --parallel 4

Generering af dokumentation på engelsk

cmake -S sti/til/kilde -B sti/til/bygningsmappe -DCMAKE_BUILD_TYPE=Release -DMYLIB_DOXYGEN_LANGUAGE=English
cmake --build sti/til/bygningsmappe --target doc

Værktøjer

CMake 3.13
Faktisk kræves CMake version 3.13 kun for at køre visse konsolkommandoer, der er beskrevet i denne vejledning. Med hensyn til syntaksen i CMake-scripts er version 3.8 tilstrækkelig, hvis genereringen kaldes på andre måder.
Testbibliotek doctest
Testning kan deaktiveres (se option MYLIB_TESTING).
Doxygen
For at skifte sprog, som dokumentationen genereres på, er der en mulighed MYLIB_DOXYGEN_LANGUAGE.
Tolk for programmeringssprog Python 3
Til automatisk generering online-sandbox.

Statisk analyse

Med CMake og et par gode værktøjer kan statisk analyse sikres med minimal indsats.

Cppcheck

CMake har indbygget support for værktøjet til statisk analyse Cppcheck.

For dette skal du bruge indstillingen CMAKE_CXX_CPPCHECK:

cmake -S sti/til/kilde -B sti/til/bygningsmappe -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_CPPCHECK="cppcheck;--enable=all;-Isti/til/kilde/include"

Efter dette vil den statiske analyse automatisk blive udført hver gang der kompileres og rekonstrueres kilden. Der er ikke behov for at foretage yderligere handlinger.

Clang

Ved hjælp af det vidunderlige værktøj scan-build kan du også køre statisk analyse på ingen tid:

scan-build cmake -S sti/til/kilde -B sti/til/bygningsmappe -DCMAKE_BUILD_TYPE=Debug
scan-build cmake --build sti/til/bygningsmappe

Her, i modsætning til tilfælde med Cppcheck, kræves det at bygge igen hver gang via scan-build.

Efterord

CMake er et meget kraftfuldt og fleksibelt system, der gør det muligt at implementere funktionalitet i enhver smag og farve. Og selvom syntaksen til tider kan være mere ønskelig, er det ikke så skræmmende, som det lyder. Brug CMake-byggeværktøjet til gavn for samfundet og til gavn for dit helbred.

→ Download projekt-skabelonen

Kilde: habr.com