CMake dan C++ adalah saudara selamanya

Semasa pembangunan, saya suka menukar penyusun, membina mod, versi pergantungan, melakukan analisis statik, mengukur prestasi, mengumpul liputan, menjana dokumentasi, dsb. Dan saya sangat menyukai CMake kerana ia membolehkan saya melakukan semua yang saya mahu.

Ramai orang mengkritik CMake, dan selalunya sepatutnya begitu, tetapi jika anda melihatnya, tidak semuanya begitu buruk, dan baru-baru ini boleh tahan juga, dan hala tuju pembangunan agak positif.

Dalam nota ini, saya ingin memberitahu anda cara mengatur perpustakaan pengepala dalam C++ dalam sistem CMake untuk mendapatkan fungsi berikut:

1. Perhimpunan;
2. Ujian autorun;
3. Pengukuran liputan kod;
4. Pemasangan;
5. Autodokumentasi;
6. Penjanaan kotak pasir dalam talian;
7. Analisis statik.

Sesiapa yang sudah faham kelebihan dan C-make boleh sahaja muat turun templat projek dan mula menggunakannya.

Содержание

1. Projek dari dalam
   1. Struktur projek
   2. Fail CMake utama (./CMakeLists.txt)
      1. Maklumat projek
      2. Pilihan Projek
      3. Pilihan kompilasi
      4. Matlamat utama
      5. Pemasangan
      6. Ujian
      7. Dokumentasi
      8. Kotak pasir dalam talian
   3. Skrip ujian (test/CMakeLists.txt)
      1. Ujian
      2. Liputan
   4. Skrip untuk dokumentasi (doc/CMakeLists.txt)
   5. Skrip untuk kotak pasir dalam talian (dalam talian/CMakeLists.txt)
2. Projek di luar
   1. Perhimpunan
      1. Generasi
      2. Perhimpunan
   2. Pilihan
      1. MYLIB_COVERAGE
      2. MYLIB_TESTING
      3. MYLIB_DOXYGEN_LANGUAGE
   3. Sasaran perhimpunan
      1. По умолчанию
      2. mylib-unit-tests
      3. menyemak
      4. liputan
      5. doc
      6. kotak tongkat
   4. contoh
3. Tools
4. Analisis statik
5. afterword

Projek dari dalam

Struktur projek

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

Kami terutamanya akan bercakap tentang cara mengatur skrip CMake, jadi ia akan dibincangkan secara terperinci. Sesiapa sahaja boleh melihat seluruh fail secara langsung pada halaman projek templat.

Fail CMake utama (./CMakeLists.txt)

Maklumat projek

Pertama sekali, anda perlu meminta versi sistem CMake yang diperlukan. CMake sedang berkembang, tandatangan perintah dan tingkah laku dalam keadaan berbeza berubah. Untuk membolehkan CMake memahami dengan segera apa yang kami mahu daripadanya, kami perlu segera merekodkan keperluan kami untuknya.

cmake_minimum_required(VERSION 3.13)

Kemudian kami akan menetapkan projek kami, namanya, versi, bahasa yang digunakan, dll. (lihat. команду project).

Dalam kes ini kami menunjukkan bahasa CXX (dan ini bermakna C++) supaya CMake tidak meneran dan mencari pengkompil bahasa C (secara lalai, CMake termasuk dua bahasa: C dan C++).

project(Mylib VERSION 1.0 LANGUAGES CXX)

Di sini anda boleh segera menyemak sama ada projek kami termasuk dalam projek lain sebagai subprojek. Ini akan banyak membantu pada masa hadapan.

get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Pilihan Projek

Kami akan menyediakan dua pilihan.

Pilihan pertama ialah MYLIB_TESTING — untuk melumpuhkan ujian unit. Ini mungkin perlu jika kami yakin bahawa semuanya teratur dengan ujian, tetapi kami hanya mahu, sebagai contoh, memasang atau membungkus projek kami. Atau projek kami disertakan sebagai subprojek - dalam kes ini, pengguna projek kami tidak berminat untuk menjalankan ujian kami. Anda tidak menguji kebergantungan yang anda gunakan, bukan?

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

Di samping itu, kami akan membuat pilihan yang berasingan MYLIB_COVERAGE untuk mengukur liputan kod melalui ujian, tetapi ia memerlukan alat tambahan, jadi ia perlu didayakan secara eksplisit.

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

Pilihan kompilasi

Sudah tentu, kami adalah pengaturcara tambah yang hebat, jadi kami mahukan tahap maksimum diagnostik masa kompilasi daripada pengkompil. Tiada satu tetikus pun akan tergelincir.

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
)

Kami juga akan melumpuhkan sambungan untuk mematuhi sepenuhnya standard bahasa C++. Ia didayakan secara lalai dalam CMake.

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

Matlamat utama

Pustaka kami hanya terdiri daripada fail pengepala, yang bermaksud kami tidak mempunyai sebarang ekzos dalam bentuk perpustakaan statik atau dinamik. Sebaliknya, untuk menggunakan perpustakaan kami secara luaran, ia perlu dipasang, ia perlu dikesan dalam sistem dan disambungkan ke projek anda, dan pada masa yang sama pengepala yang sama ini, serta mungkin beberapa tambahan, adalah melekat padanya sifat.

Untuk tujuan ini, kami mencipta perpustakaan antara muka.

add_library(mylib INTERFACE)

Kami mengikat pengepala ke perpustakaan antara muka kami.

Penggunaan CMake yang moden, bergaya, belia membayangkan bahawa pengepala, sifat, dsb. dihantar melalui satu sasaran. Jadi cukuplah untuk mengatakannya target_link_libraries(target PRIVATE dependency), dan semua pengepala yang dikaitkan dengan sasaran dependency, akan tersedia untuk sumber milik sasaran target. Dan anda tidak memerlukan apa-apa [target_]include_directories. Ini akan ditunjukkan di bawah dalam analisis Skrip CMake untuk ujian unit.

Ia juga bernilai memberi perhatian kepada apa yang dipanggil. выражения-генераторы: $<...>.

Perintah ini mengaitkan pengepala yang kami perlukan dengan pustaka antara muka kami, dan jika pustaka kami disambungkan ke mana-mana sasaran dalam hierarki CMake yang sama, maka pengepala daripada direktori akan dikaitkan dengannya ${CMAKE_CURRENT_SOURCE_DIR}/include, dan jika perpustakaan kami dipasang pada sistem dan disambungkan ke projek lain menggunakan arahan find_package, maka pengepala daripada direktori akan dikaitkan dengannya include berbanding dengan direktori pemasangan.

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

Mari kita tetapkan standard bahasa. Sudah tentu, yang terakhir. Pada masa yang sama, kami bukan sahaja memasukkan standard, tetapi juga memanjangkannya kepada mereka yang akan menggunakan perpustakaan kami. Ini dicapai kerana hakikat bahawa harta yang ditetapkan mempunyai kategori INTERFACE (Lihat. arahan target_compile_features).

target_compile_features(mylib INTERFACE cxx_std_17)

Mari buat alias untuk perpustakaan kami. Lebih-lebih lagi, untuk kecantikan, ia akan berada dalam "ruang nama" khas. Ini akan berguna apabila modul berbeza muncul dalam pustaka kami, dan kami menyambungkannya secara berasingan antara satu sama lain. Seperti di Busta, sebagai contoh.

add_library(Mylib::mylib ALIAS mylib)

Pemasangan

Memasang pengepala kami ke dalam sistem. Semuanya mudah di sini. Kami mengatakan bahawa folder dengan semua pengepala harus masuk ke dalam direktori include berbanding dengan lokasi pemasangan.

install(DIRECTORY include/mylib DESTINATION include)

Seterusnya, kami memaklumkan sistem binaan bahawa kami ingin dapat memanggil arahan dalam projek pihak ketiga find_package(Mylib) dan dapatkan matlamat Mylib::mylib.

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

Mantera seterusnya harus difahami dengan cara ini. Apabila dalam projek pihak ketiga kami memanggil arahan find_package(Mylib 1.2.3 REQUIRED), dan versi sebenar pustaka yang dipasang akan tidak serasi dengan versi 1.2.3CMake akan menjana ralat secara automatik. Iaitu, anda tidak perlu menjejak versi secara manual.

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)

Ujian

Jika ujian dilumpuhkan secara eksplisit menggunakan pilihan yang sepadan atau projek kami ialah subprojek, iaitu, ia disambungkan kepada projek CMake yang lain menggunakan arahan add_subdirectory, kami tidak bergerak lebih jauh mengikut hierarki, dan skrip, yang menerangkan arahan untuk menjana dan menjalankan ujian, langsung tidak berjalan.

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

Dokumentasi

Dokumentasi juga tidak akan dihasilkan dalam kes subprojek.

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

Kotak pasir dalam talian

Begitu juga, subprojek tidak akan mempunyai kotak pasir dalam talian sama ada.

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

Skrip ujian (test/CMakeLists.txt)

Ujian

Pertama sekali, kami mencari pakej dengan rangka kerja ujian yang diperlukan (ganti dengan yang kegemaran anda).

find_package(doctest 2.3.3 REQUIRED)

Mari buat fail boleh laku kami dengan ujian. Biasanya saya menambah terus ke binari boleh laku hanya fail yang akan mengandungi fungsi main.

add_executable(mylib-unit-tests test_main.cpp)

Dan saya menambah fail di mana ujian itu sendiri diterangkan kemudian. Tetapi anda tidak perlu berbuat demikian.

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

Kami menyambung kebergantungan. Sila ambil perhatian bahawa kami hanya memautkan sasaran CMake yang kami perlukan kepada binari kami dan tidak memanggil arahan itu target_include_directories. Tajuk daripada rangka kerja ujian dan daripada kami Mylib::mylib, serta parameter binaan (dalam kes kami, ini ialah standard bahasa C++) dicapai bersama-sama dengan matlamat ini.

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

Akhir sekali, kami mencipta sasaran tiruan, "binaan" yang bersamaan dengan menjalankan ujian dan menambah sasaran ini pada binaan lalai (atribut bertanggungjawab untuk ini ALL). Ini bermakna binaan lalai mencetuskan ujian untuk dijalankan, bermakna kita tidak akan lupa untuk menjalankannya.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Liputan

Seterusnya, kami mendayakan pengukuran liputan kod jika pilihan yang sesuai ditentukan. Saya tidak akan menerangkan secara terperinci, kerana ia lebih berkaitan dengan alat untuk mengukur liputan berbanding CMake. Hanya penting untuk ambil perhatian bahawa berdasarkan keputusan matlamat akan dibuat coverage, yang mudah untuk mula mengukur liputan.

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

Skrip untuk dokumentasi (doc/CMakeLists.txt)

Ditemui Doksigen.

find_package(Doxygen)

Seterusnya, kami menyemak sama ada pengguna telah menetapkan pembolehubah bahasa. Jika ya, maka kami tidak menyentuhnya, jika tidak, maka kami mengambil bahasa Rusia. Kemudian kami mengkonfigurasi fail sistem Doxygen. Semua pembolehubah yang diperlukan, termasuk bahasa, pergi ke sana semasa proses konfigurasi (lihat. команду configure_file).

Kemudian kita mencipta matlamat doc, yang akan mula menjana dokumentasi. Memandangkan penjanaan dokumentasi bukanlah keperluan terbesar dalam proses pembangunan, sasaran tidak akan didayakan secara lalai; ia perlu dilancarkan secara eksplisit.

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

Skrip untuk kotak pasir dalam talian (dalam talian/CMakeLists.txt)

Di sini kita dapati Python ketiga dan mencipta sasaran wandbox, yang menjana permintaan yang sepadan dengan API perkhidmatan Kotak tongkat, dan menghantarnya pergi. Sambutan datang dengan pautan ke kotak pasir yang telah siap.

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

Projek di luar

Sekarang mari kita lihat bagaimana untuk menggunakan semua ini.

Perhimpunan

Membina projek ini, seperti mana-mana projek lain pada sistem binaan CMake, terdiri daripada dua peringkat:

Generasi

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

Jika arahan di atas tidak berfungsi kerana versi lama CMake, cuba tinggalkan -S:

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

Lebih lanjut mengenai pilihan.

Membina projek

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

Lebih lanjut mengenai matlamat perhimpunan.

Pilihan

MYLIB_COVERAGE

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

Termasuk sasaran coverage, yang mana anda boleh mula mengukur liputan kod melalui ujian.

MYLIB_TESTING

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

Menyediakan keupayaan untuk melumpuhkan binaan dan sasaran ujian unit check. Akibatnya, pengukuran liputan kod melalui ujian dimatikan (lihat. MYLIB_COVERAGE).

Pengujian juga dilumpuhkan secara automatik jika projek disambungkan ke projek lain sebagai subprojek menggunakan arahan add_subdirectory.

MYLIB_DOXYGEN_LANGUAGE

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

Menukar bahasa dokumentasi yang dihasilkan oleh sasaran doc kepada yang diberi. Untuk senarai bahasa yang tersedia, lihat Laman web sistem doksigen.

Bahasa Rusia didayakan secara lalai.

Sasaran perhimpunan

По умолчанию

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

Jika sasaran tidak dinyatakan (yang bersamaan dengan sasaran all), mengumpul semua yang boleh, dan juga memanggil sasaran check.

mylib-unit-tests

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

Menyusun ujian unit. Didayakan secara lalai.

menyemak

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

Menjalankan ujian unit yang dikumpul (dikumpul, jika belum). Didayakan secara lalai.

Lihat juga mylib-unit-tests.

liputan

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

Menganalisis ujian unit berjalan (berjalan, jika belum) untuk liputan kod dengan ujian menggunakan program gcovr.

Ekzos salutan akan kelihatan seperti ini:

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

Sasaran hanya tersedia apabila pilihan didayakan MYLIB_COVERAGE.

Lihat juga check.

doc

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

Memulakan penjanaan dokumentasi kod menggunakan sistem Doksigen.

kotak tongkat

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

Maklum balas daripada perkhidmatan kelihatan seperti ini:

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

Perkhidmatan ini digunakan untuk ini Kotak tongkat. Saya tidak tahu betapa fleksibelnya pelayan mereka, tetapi saya berpendapat bahawa peluang ini tidak seharusnya disalahgunakan.

contoh

Bina projek dalam mod nyahpepijat dengan ukuran liputan

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

Memasang projek tanpa pemasangan dan ujian awal

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

Bina dalam mod keluaran dengan pengkompil yang diberikan

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

Menjana dokumentasi dalam bahasa Inggeris

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

Tools

1. CMake 3.13

   Sebenarnya, CMake versi 3.13 hanya diperlukan untuk menjalankan beberapa arahan konsol yang diterangkan dalam bantuan ini. Dari sudut pandangan sintaks skrip CMake, versi 3.8 adalah mencukupi jika penjanaan dipanggil dengan cara lain.

2. Menguji perpustakaan ahli doktrin

   Ujian boleh dilumpuhkan (lihat опцию MYLIB_TESTING).

3. Doksigen

   Untuk menukar bahasa di mana dokumentasi akan dijana, pilihan disediakan MYLIB_DOXYGEN_LANGUAGE.

4. Penterjemah bahasa Python 3

   Untuk penjanaan automatik kotak pasir dalam talian.

Analisis statik

Dengan CMake dan beberapa alat yang baik, anda boleh menyediakan analisis statik dengan usaha yang minimum.

Cppcheck

CMake mempunyai sokongan terbina dalam untuk alat analisis statik Cppcheck.

Untuk melakukan ini, anda perlu menggunakan pilihan CMAKE_CXX_CPPCHECK:

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

Selepas ini, analisis statik akan dilancarkan secara automatik setiap kali sumber disusun dan disusun semula. Tidak perlu melakukan apa-apa tambahan.

Dakap

Dengan bantuan alat yang hebat scan-build Anda juga boleh menjalankan analisis statik dalam masa yang singkat:

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

Di sini, tidak seperti kes dengan Cppcheck, anda perlu menjalankan binaan setiap kali melalui scan-build.

afterword

CMake ialah sistem yang sangat berkuasa dan fleksibel yang membolehkan anda melaksanakan fungsi untuk setiap rasa dan warna. Dan, walaupun sintaks kadang-kadang meninggalkan banyak yang diingini, syaitan masih tidak seteruk yang dilukisnya. Gunakan sistem binaan CMake untuk manfaat masyarakat dan kesihatan.

→ Muat turun templat projek

Sumber: www.habr.com