🇬🇧 English version

Шаблон проекта на основе системы сборки CMake для языка C++

Склонируйте и поменяйте "Mylib" на своё название.

Либо сгенерируйте свой проект с помощью скрипта: https://github.com/izvolov/mylib-gen

Содержание

1. Сборка
   1. Генерация
   2. Сборка
2. Опции
   1. MYLIB_COVERAGE
   2. MYLIB_TESTING
   3. DOXYGEN_OUTPUT_LANGUAGE
3. Сборочные цели
   1. По умолчанию
   2. mylib_library
   3. mylib-unit-tests
   4. check
   5. coverage
   6. doc
   7. wandbox
4. Примеры
5. Использование
   1. Через установку
   2. В качестве подмодуля
6. Инструменты
7. Бонус

Сборка

Сборка данного проекта, как и любого другого проекта на системе сборки CMake, состоит из двух этапов:

Генерация

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

Подробнее про опции.

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

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

Подробнее про сборочные цели.

Опции

MYLIB_COVERAGE

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

Включает цель coverage, с помощью которой можно запустить замер покрытия кода тестами.

MYLIB_TESTING

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

Предоставляет возможность выключить сборку модульных тестов и цель check. Как следствие, выключается замер покрытия кода тестами (см. Покрытие).

Также тестирование автоматически отключается в случае, если проект подключается в другой проект качестве подпроекта с помощью команды add_subdirectory.

DOXYGEN_OUTPUT_LANGUAGE

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

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

По умолчанию включён русский.

Сборочные цели

По умолчанию

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

Если цель не указана (что эквивалентно цели all), собирает всё, что можно, а также вызывает цель check.

mylib_library

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

Компилирует библиотеку mylib_library. Включено по умолчанию.

mylib-unit-tests

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

Компилирует модульные тесты. Включено по умолчанию.

check

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

Запускает собранные (собирает, если ещё не) модульные тесты. Включено по умолчанию.

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

coverage

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

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

Цель доступна только при включённой опции MYLIB_COVERAGE.

См. также check.

doc

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

Запускает генерацию документации к коду при помощи системы Doxygen.

wandbox

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

Для этого используется сервис 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 -DDOXYGEN_OUTPUT_LANGUAGE=English
cmake --build путь/к/сборочной/директории --target doc

Использование

Через установку

Один из вариантов использования модуля — установить его в систему.

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

После этого любой другой проект, вызвав команду find_package, получает возможность использовать все библиотеки из пространства имён Mylib:::

find_package(Mylib 1.0 REQUIRED)

add_executable(some_executable some.cpp sources.cpp)
target_link_libraries(some_executable PRIVATE Mylib::library)

Библиотеку Mylib::library нужно подключать тогда, когда необходимо слинковаться с библиотекой libmylib_library. Если достаточно заголовков, то тогда стоит использовать библиотеку Mylib::headers.

В качестве подмодуля

Также проект может быть подключён к другому проекту в качестве подмодуля с помощью команды add_subdirectory.

В этом случае аналогичным образом будут доступны библиотеки Mylib::library и Mylib::headers.

Инструменты

1. CMake 3.14

   CMake 3.14 требуется потому, что в предыдущих версиях некорректно работает команда install(TARGETS ... EXPORT ...), а именно — не прописываются пути по умолчанию.

2. Библиотека тестирования doctest

   Тестирование можно отключать (см. Тестирование).

3. Doxygen

   Для переключения языка, на котором будет сгенерирована документация, предусмотрена опция DOXYGEN_OUTPUT_LANGUAGE.

4. Интерпретатор ЯП 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.