🥇CMake ו-C++ הם אחים לנצח

במהלך הפיתוח, אני אוהב לשנות מהדרים, לבנות מצבים, גרסאות תלות, לבצע ניתוח סטטי, למדוד ביצועים, לאסוף כיסוי, ליצור תיעוד וכו'. ואני מאוד אוהב את CMake כי זה מאפשר לי לעשות כל מה שאני רוצה.

אנשים רבים מבקרים את CMake, ולעתים קרובות בצדק, אבל אם מסתכלים על זה, לא הכל כל כך גרוע, ולאחרונה לא רע בכלל, וכיוון ההתפתחות הוא די חיובי.

בהערה זו, אני רוצה לספר לך איך פשוט לארגן ספריית כותרות ב-C++ במערכת CMake כדי לקבל את הפונקציונליות הבאה:

הַרכָּבָה;
בדיקות אוטומטיות;
מדידת כיסוי קוד;
הַתקָנָה;
תיעוד אוטומטי;
יצירת ארגז חול מקוון;
ניתוח סטטי.

מי שכבר מבין את היתרונות ואת C-make יכול פשוט הורד תבנית פרויקט ולהתחיל להשתמש בו.

האפשרות הראשונה היא MYLIB_TESTING - כדי להשבית בדיקות יחידה. זה אולי נחוץ אם אנחנו בטוחים שהכל תקין עם הבדיקות, אבל אנחנו רק רוצים, למשל, להתקין או לארוז את הפרויקט שלנו. או שהפרויקט שלנו נכלל כתת-פרויקט - במקרה זה, המשתמש בפרויקט שלנו לא מעוניין להפעיל את הבדיקות שלנו. אתה לא בודק את התלות שבה אתה משתמש, נכון?

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

בנוסף, נבצע אופציה נפרדת MYLIB_COVERAGE למדידת כיסוי קוד על ידי בדיקות, אבל זה ידרוש כלים נוספים, ולכן יהיה צורך להפעיל אותו במפורש.

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

אפשרויות קומפילציה

כמובן, אנחנו מתכנתים מגניבים, אז אנחנו רוצים את הרמה המקסימלית של אבחון בזמן הידור מהקומפיילר. אף עכבר אחד לא יחמוק.

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. זה יודגם להלן בניתוח C צור סקריפט עבור בדיקות יחידה.

כדאי גם לשים לב למה שנקרא. выражения-генераторы: $<...>.

פקודה זו משייכת את הכותרות שאנו צריכים לספריית הממשק שלנו, ואם הספרייה שלנו מחוברת ליעד כלשהו בתוך אותה היררכיית CMake, אז הכותרות מהספרייה ישויכות אליה ${CMAKE_CURRENT_SOURCE_DIR}/include, ואם הספרייה שלנו מותקנת על המערכת ומחוברת לפרויקט אחר באמצעות הפקודה find_package, אז כותרות מהספרייה ישויכות אליו include ביחס לספריית ההתקנה.

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

בואו נקבע סטנדרט שפה. כמובן, האחרון ממש. יחד עם זאת, אנחנו לא רק כוללים את התקן, אלא גם מרחיבים אותו למי שישתמש בספרייה שלנו. זה מושג בגלל העובדה שלמאפיין הסט יש קטגוריה INTERFACE (ראה הפקודה target_compile_features).

target_compile_features(mylib INTERFACE cxx_std_17)

בואו ניצור כינוי לספרייה שלנו. יתר על כן, למען היופי, זה יהיה ב"מרחב שמות" מיוחד. זה יהיה שימושי כאשר מודולים שונים מופיעים בספרייה שלנו, ואנחנו הולכים לחבר אותם ללא תלות זה בזה. כמו בבוסטה, למשל.

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.3CMake יפיק שגיאה אוטומטית. כלומר, לא תצטרך לעקוב אחר גרסאות באופן ידני.

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
)

לבסוף, אנו יוצרים יעד דמה, ש"הבנייה" שלו שווה ערך להפעלת בדיקות, ומוסיפים יעד זה ל-build ברירת המחדל (התכונה אחראית לכך ALL). המשמעות היא ש-build ברירת המחדל מפעיל את הבדיקות, כלומר לעולם לא נשכח להפעיל אותן.

add_custom_target(check ALL COMMAND mylib-unit-tests)

ציפוי

לאחר מכן, אנו מאפשרים מדידת כיסוי קוד אם צוינה האפשרות המתאימה. אני לא אכנס לפרטים, כי הם מתייחסים יותר לכלי למדידת כיסוי מאשר ל-CMake. חשוב רק לציין שעל סמך התוצאות תיווצר מטרה coverage, שאיתו נוח להתחיל למדוד כיסוי.

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)

מצא את דוקסיגן.

find_package(Doxygen)

לאחר מכן, נבדוק האם המשתמש הגדיר את משתנה השפה. אם כן, אז אנחנו לא נוגעים בזה, אם לא, אז אנחנו לוקחים רוסית. לאחר מכן אנו מגדירים את קבצי מערכת Doxygen. כל המשתנים הדרושים, כולל השפה, עוברים לשם במהלך תהליך ההגדרה (ראה. команду configure_file).

ואז אנחנו יוצרים מטרה doc, שיתחיל לייצר תיעוד. מכיוון שהפקת תיעוד אינה הצורך הגדול ביותר בתהליך הפיתוח, היעד לא יופעל כברירת מחדל; הוא יצטרך להיות מופעל במפורש.

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

סקריפט עבור ארגז חול מקוון (online/CMakeLists.txt)

כאן אנו מוצאים את הפייתון השלישי ויוצרים מטרה 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 3-й версии")
endif()

פרויקט בחוץ

עכשיו בואו נסתכל איך להשתמש בכל זה.

העצרת

בניית פרויקט זה, כמו כל פרויקט אחר במערכת ה-Build CMake, מורכבת משני שלבים:

דור

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

אם הפקודה למעלה לא עבדה בגלל גרסה ישנה של CMake, נסה להשמיט -S:
cmake путь/к/исходникам -B путь/к/сборочной/директории [опции ...]

עוד על אפשרויות.

בניית הפרויקט

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

עוד על יעדי הרכבה.

אפשרויות

MYLIB_COVERAGE

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

כולל מטרה coverage, שבאמצעותו אתה יכול להתחיל למדוד כיסוי קוד על ידי בדיקות.

MYLIB_TESTING

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

מספק את היכולת להשבית את הבנייה והמטרה של בדיקות יחידה check. כתוצאה מכך, מדידת כיסוי הקוד על ידי בדיקות מבוטלת (ראה. MYLIB_COVERAGE).

הבדיקה גם מושבתת אוטומטית אם הפרוייקט מחובר לפרויקט אחר כתת-פרויקט באמצעות הפקודה add_subdirectory.

MYLIB_DOXYGEN_LANGUAGE

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

מחליף את שפת התיעוד שהיעד מייצר doc לנתון. לרשימה של שפות זמינות, ראה אתר מערכת דוקסיג'ן.

רוסית מופעלת כברירת מחדל.

מטרות הרכבה

ברירת מחדל

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

מרכיב בדיקות יחידה. מופעל כברירת מחדל.

לבדוק

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.

doc

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

מתחיל יצירת תיעוד קוד באמצעות המערכת חמצן.

תיבת שרביטים

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 מספיקה אם הדור נקרא בדרכים אחרות.
ספריית בדיקות דוקטסט

ניתן להשבית את הבדיקה (ראה опцию MYLIB_TESTING).
חמצן

כדי להחליף את השפה שבה יופק התיעוד, ניתנת אפשרות MYLIB_DOXYGEN_LANGUAGE.
מתורגמן לשפות פייתון 3

ליצירה אוטומטית ארגזי חול מקוונים.

ניתוח סטטי

עם CMake וכמה כלים טובים, אתה יכול לספק ניתוח סטטי במינימום מאמץ.

Cppcheck

ל-CMake תמיכה מובנית בכלי ניתוח סטטי Cppcheck.

כדי לעשות זאת אתה צריך להשתמש באפשרות CMAKE_CXX_CPPCHECK:

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

לאחר מכן, ניתוח סטטי יופעל אוטומטית בכל פעם שהמקור יודר והידור מחדש. אין צורך לעשות שום דבר נוסף.

קלאנג

בעזרת כלי נפלא scan-build אתה יכול גם להפעיל ניתוח סטטי תוך זמן קצר:

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

כאן, בניגוד למקרה עם Cppcheck, אתה צריך להפעיל את ה-build בכל פעם scan-build.

אחרית דבר

CMake היא מערכת חזקה וגמישה מאוד המאפשרת ליישם פונקציונליות לכל טעם וצבע. ולמרות שהתחביר לפעמים משאיר הרבה לרצוי, השטן עדיין לא נורא כמו שהוא מצויר. השתמש במערכת CMake build לטובת החברה והבריאות.

→ הורד תבנית פרויקט

מקור: www.habr.com

CMake ו-C++ הם אחים לנצח