🥇CMake dan C++ bersaudara selamanya

Selama pengembangan, saya suka mengubah kompiler, mode build, versi ketergantungan, melakukan analisis statis, mengukur kinerja, mengumpulkan cakupan, membuat dokumentasi, dll. Dan saya sangat menyukai CMake karena memungkinkan saya melakukan apa pun yang saya inginkan.

Banyak orang mengkritik CMake, dan seringkali memang sepantasnya demikian, namun jika Anda melihatnya, tidak semuanya begitu buruk, dan baru-baru ini tidak buruk sama sekali, dan arah pengembangannya cukup positif.

Dalam catatan ini, saya ingin memberi tahu Anda cara mengatur pustaka header di C++ di sistem CMake untuk mendapatkan fungsionalitas berikut:

Perakitan;
Tes jalan otomatis;
Pengukuran cakupan kode;
Instalasi;
Dokumentasi otomatis;
Pembuatan kotak pasir online;
Analisis statis.

Siapapun yang sudah paham kelebihan dan C-make bisa langsung saja unduh templat proyek dan mulai menggunakannya.

Proyek dari dalam

Struktur proyek

.
├── 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 terutama akan berbicara tentang cara mengatur skrip CMake, sehingga akan dibahas secara detail. Siapapun dapat melihat sisa file secara langsung di halaman proyek templat.

File CMake utama (./CMakeLists.txt)

Informasi Proyek

Pertama-tama, Anda perlu meminta versi sistem CMake yang diperlukan. CMake terus berkembang, tanda tangan perintah, dan perilaku dalam kondisi berbeda pun berubah. Agar CMake segera memahami apa yang kita inginkan darinya, kita perlu segera mencatat persyaratan kita terhadapnya.

cmake_minimum_required(VERSION 3.13)

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

Dalam hal ini kami menunjukkan bahasanya CXX (dan ini berarti C++) sehingga CMake tidak tegang dan mencari kompiler bahasa C (secara default, CMake menyertakan dua bahasa: C dan C++).

project(Mylib VERSION 1.0 LANGUAGES CXX)

Di sini Anda dapat langsung memeriksa apakah proyek kita termasuk dalam proyek lain sebagai subproyek. Ini akan sangat membantu di masa depan.

get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)

Opsi Proyek

Kami akan memberikan dua opsi.

Opsi pertama adalah MYLIB_TESTING — untuk menonaktifkan pengujian unit. Ini mungkin diperlukan jika kami yakin semuanya beres dengan pengujian, tetapi kami hanya ingin, misalnya, menginstal atau mengemas proyek kami. Atau proyek kami disertakan sebagai subproyek - dalam hal ini, pengguna proyek kami tidak tertarik untuk menjalankan pengujian kami. Anda tidak menguji dependensi yang Anda gunakan, bukan?

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

Selain itu, kami akan membuat opsi terpisah MYLIB_COVERAGE untuk mengukur cakupan kode melalui pengujian, namun memerlukan alat tambahan, sehingga perlu diaktifkan secara eksplisit.

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

Opsi kompilasi

Tentu saja, kami adalah programmer yang keren plus, jadi kami menginginkan tingkat diagnostik waktu kompilasi yang maksimal dari compiler. Tidak ada seekor tikus pun yang lolos.

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 menonaktifkan ekstensi agar sepenuhnya mematuhi standar bahasa C++. Mereka diaktifkan secara default di CMake.

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

Tujuan utama

Library kami hanya terdiri dari file header saja, artinya kami tidak memiliki exhaust apapun berupa library statis maupun dinamis. Di sisi lain, untuk menggunakan perpustakaan kami secara eksternal, perpustakaan tersebut perlu diinstal, harus dapat dideteksi di sistem dan terhubung ke proyek Anda, dan pada saat yang sama header yang sama, serta mungkin beberapa header tambahan, melekat padanya properti.

Untuk tujuan ini, kami membuat perpustakaan antarmuka.

add_library(mylib INTERFACE)

Kami mengikat header ke perpustakaan antarmuka kami.

Penggunaan CMake yang modern, modis, dan awet muda menyiratkan bahwa header, properti, dll. ditransmisikan melalui satu sasaran tunggal. Jadi cukuplah untuk mengatakannya target_link_libraries(target PRIVATE dependency), dan semua header yang terkait dengan target dependency, akan tersedia untuk sumber milik target target. Dan Anda tidak membutuhkannya [target_]include_directories. Hal ini akan ditunjukkan di bawah dalam analisis Skrip CMake untuk pengujian unit.

Perlu juga memperhatikan apa yang disebut. выражения-генераторы: $<...>.

Perintah ini mengaitkan header yang kita butuhkan dengan perpustakaan antarmuka kita, dan jika perpustakaan kita terhubung ke target mana pun dalam hierarki CMake yang sama, maka header dari direktori akan dikaitkan dengannya ${CMAKE_CURRENT_SOURCE_DIR}/include, dan jika perpustakaan kita diinstal pada sistem dan terhubung ke proyek lain menggunakan perintah find_package, maka header dari direktori akan dikaitkan dengannya include relatif terhadap direktori instalasi.

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

Mari kita tetapkan standar bahasa. Tentu saja yang terakhir. Pada saat yang sama, kami tidak hanya menyertakan standar tersebut, tetapi juga memperluasnya kepada mereka yang akan menggunakan perpustakaan kami. Hal ini dicapai karena properti himpunan memiliki kategori INTERFACE (Lihat. perintah target_compile_features).

target_compile_features(mylib INTERFACE cxx_std_17)

Mari buat alias untuk perpustakaan kita. Apalagi untuk kecantikan akan berada di “namespace” khusus. Ini akan berguna ketika modul yang berbeda muncul di perpustakaan kita, dan kita akan menghubungkannya secara independen satu sama lain. Seperti di Busta misalnya.

add_library(Mylib::mylib ALIAS mylib)

Instalasi

Memasang header kami ke dalam sistem. Semuanya sederhana di sini. Kami mengatakan bahwa folder dengan semua header harus masuk ke direktori include relatif terhadap lokasi pemasangan.

install(DIRECTORY include/mylib DESTINATION include)

Selanjutnya, kami memberi tahu sistem build bahwa kami ingin dapat memanggil perintah di proyek pihak ketiga find_package(Mylib) dan mendapatkan gol Mylib::mylib.

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

Mantra selanjutnya harus dipahami seperti ini. Saat berada di proyek pihak ketiga kami memanggil perintah find_package(Mylib 1.2.3 REQUIRED), dan versi sebenarnya dari perpustakaan yang diinstal tidak akan kompatibel dengan versi tersebut 1.2.3CMake secara otomatis akan menghasilkan kesalahan. Artinya, Anda tidak perlu melacak 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)

Uji

Jika tes dinonaktifkan secara eksplisit menggunakan pilihan yang sesuai atau proyek kita adalah subproyek, yaitu terhubung ke proyek CMake lain menggunakan perintah add_subdirectory, kami tidak bergerak lebih jauh dalam hierarki, dan skrip yang menjelaskan perintah untuk membuat dan menjalankan pengujian tidak berjalan.

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

Документация

Dokumentasi juga tidak akan dibuat jika ada subproyek.

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

Kotak pasir daring

Demikian pula, subproyek juga tidak akan memiliki sandbox online.

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

Skrip pengujian (test/CMakeLists.txt)

Pengujian

Pertama-tama, kami menemukan paket dengan kerangka pengujian yang diperlukan (ganti dengan yang favorit Anda).

find_package(doctest 2.3.3 REQUIRED)

Mari buat file yang dapat dieksekusi dengan tes. Biasanya saya menambahkan langsung ke biner yang dapat dieksekusi hanya file yang berisi fungsi tersebut main.

add_executable(mylib-unit-tests test_main.cpp)

Dan saya menambahkan file yang tesnya sendiri akan dijelaskan nanti. Tapi Anda tidak perlu melakukan itu.

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

Kami menghubungkan dependensi. Harap dicatat bahwa kami hanya menautkan target CMake yang kami perlukan ke biner kami dan tidak memanggil perintah target_include_directories. Judul dari kerangka pengujian dan dari kami Mylib::mylib, serta parameter build (dalam kasus kami, ini adalah standar bahasa C++) yang berhasil mencapai tujuan ini.

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

Terakhir, kami membuat target dummy, yang "build"-nya setara dengan menjalankan pengujian, dan menambahkan target ini ke build default (atribut bertanggung jawab untuk ini ALL). Ini berarti bahwa build default memicu pengujian untuk dijalankan, yang berarti kita tidak akan pernah lupa untuk menjalankannya.

add_custom_target(check ALL COMMAND mylib-unit-tests)

Liputan

Selanjutnya, kami mengaktifkan pengukuran cakupan kode jika opsi yang sesuai ditentukan. Saya tidak akan menjelaskan secara detail, karena ini lebih berkaitan dengan alat untuk mengukur cakupan dibandingkan dengan CMake. Penting untuk dicatat bahwa berdasarkan hasil akan tercipta gol coverage, yang memudahkan untuk mulai mengukur cakupan.

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)

Menemukan Doksigen.

find_package(Doxygen)

Selanjutnya, kami memeriksa apakah pengguna telah menyetel variabel bahasa. Jika ya, maka kami tidak menyentuhnya, jika tidak, kami mengambil bahasa Rusia. Kemudian kita konfigurasikan file sistem Doxygen. Semua variabel yang diperlukan, termasuk bahasa, ada di sana selama proses konfigurasi (lihat. команду configure_file).

Lalu kita membuat tujuan doc, yang akan mulai menghasilkan dokumentasi. Karena menghasilkan dokumentasi bukanlah kebutuhan terbesar dalam proses pengembangan, target tidak akan diaktifkan secara default; target harus diluncurkan 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 online (online/CMakeLists.txt)

Di sini kita menemukan Python ketiga dan membuat target wandbox, yang menghasilkan permintaan yang sesuai dengan API layanan Kotak tongkat, dan menyuruhnya pergi. Responsnya dilengkapi dengan tautan ke kotak pasir yang sudah selesai.

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

Proyeksikan ke luar

Sekarang mari kita lihat cara menggunakan semua ini.

Majelis

Membangun proyek ini, seperti proyek lainnya pada sistem pembangunan CMake, terdiri dari dua tahap:

Generasi

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

Jika perintah di atas tidak berfungsi karena CMake versi lama, coba hilangkan -S:
cmake путь/к/исходникам -B путь/к/сборочной/директории [опции ...]

Lebih lanjut tentang opsi.

Membangun proyek

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

Lebih lanjut tentang tujuan perakitan.

Pilihan

MYLIB_COVERAGE

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

Termasuk sasarannya coverage, yang dengannya Anda dapat mulai mengukur cakupan kode dengan pengujian.

MYLIB_TESTING

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

Memberikan kemampuan untuk menonaktifkan build dan target pengujian unit check. Akibatnya, pengukuran cakupan kode dengan pengujian dimatikan (lihat. MYLIB_COVERAGE).

Pengujian juga secara otomatis dinonaktifkan jika proyek terhubung ke proyek lain sebagai subproyek menggunakan perintah add_subdirectory.

MYLIB_DOXYGEN_LANGUAGE

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

Mengganti bahasa dokumentasi yang dihasilkan target doc kepada yang diberikan. Untuk daftar bahasa yang tersedia, lihat Situs web sistem Doxygen.

Bahasa Rusia diaktifkan secara default.

Target perakitan

По умолчанию

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

Jika target tidak ditentukan (yang setara dengan target all), mengumpulkan semua yang bisa, dan juga memanggil target check.

tes unit-mylib

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

Mengkompilasi tes unit. Diaktifkan secara default.

memeriksa

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

Menjalankan pengujian unit yang dikumpulkan (dikumpulkan, jika belum). Diaktifkan secara default.

См. также mylib-unit-tests.

liputan

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

Menganalisis pengujian unit yang berjalan (berjalan, jika belum) untuk cakupan kode dengan pengujian menggunakan program gcovr.

Lapisan knalpot akan terlihat 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%
------------------------------------------------------------------------------

Target hanya tersedia bila opsi ini diaktifkan MYLIB_COVERAGE.

См. также check.

dermaga

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

Memulai pembuatan dokumentasi kode menggunakan sistem Doksigen.

kotak tongkat sihir

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

Tanggapan dari layanan terlihat seperti ini:

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

Layanan ini digunakan untuk ini Kotak tongkat. Saya tidak tahu seberapa fleksibel server mereka, tapi menurut saya peluang ini tidak boleh disalahgunakan.

contoh

Bangun proyek dalam mode debug dengan pengukuran cakupan

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

Menginstal proyek tanpa perakitan dan pengujian awal

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

Bangun dalam mode rilis dengan kompiler tertentu

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

Menghasilkan dokumentasi dalam bahasa Inggris

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

Alat

Buat 3.13

Faktanya, CMake versi 3.13 hanya diperlukan untuk menjalankan beberapa perintah konsol yang dijelaskan dalam bantuan ini. Dari sudut pandang sintaksis skrip CMake, versi 3.8 sudah cukup jika pembangkitan dipanggil dengan cara lain.
Perpustakaan pengujian paling teruji

Pengujian dapat dinonaktifkan (lihat опцию MYLIB_TESTING).
Doksigen

Untuk mengganti bahasa dokumentasi yang akan dibuat, tersedia opsi MYLIB_DOXYGEN_LANGUAGE.
Penerjemah bahasa Python 3

Untuk pembangkitan otomatis kotak pasir online.

Analisis statis

Dengan CMake dan beberapa alat bagus, Anda dapat memberikan analisis statis dengan sedikit usaha.

Periksa cpp

CMake memiliki dukungan bawaan untuk alat analisis statis Periksa cpp.

Untuk melakukan ini, Anda perlu menggunakan opsi CMAKE_CXX_CPPCHECK:

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

Setelah ini, analisis statis akan diluncurkan secara otomatis setiap kali sumber dikompilasi dan dikompilasi ulang. Tidak perlu melakukan apa pun tambahan.

Dentang

Dengan bantuan alat yang luar biasa scan-build Anda juga dapat menjalankan analisis statis dalam waktu singkat:

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

Di sini, berbeda dengan Cppcheck, Anda perlu menjalankan build setiap saat scan-build.

penutup

CMake adalah sistem yang sangat kuat dan fleksibel yang memungkinkan Anda menerapkan fungsionalitas untuk setiap selera dan warna. Dan, meskipun sintaksisnya terkadang meninggalkan banyak hal yang diinginkan, iblis tetap tidak seburuk yang dilukiskannya. Gunakan sistem build CMake untuk kepentingan masyarakat dan kesehatan.

→ Unduh templat proyek

Sumber: www.habr.com

CMake dan C++ adalah saudara selamanya