Toliak/Guide.md

## Guide.md

      
    Raw
  

              Guide.md
            
          
    CMakeLists.txt

Прописывается основная информация для сборки через CMake.

cmake_minimum_required(VERSION 3.4)    # Минимальная версия CMake

set(CMAKE_CXX_STANDARD 17)             # Стандарт C++
set(CMAKE_CXX_STANDARD_REQUIRED ON)    # Обязательность установки указанного стандарта (если OFF (по умолчанию), то воспринимается как совет)
Прописываются возможные опции сборки (могут отсутствовать)

option(BUILD_DEMO "Build demo app" OFF)    # Название опции, описание опции и значение по умолчанию
Чтобы установить значение опции, отличное от "по умолчанию", необходимо дописать -DНАЗВАНИЕ_ОПЦИИ=Значение к команде конфигурирования.
Команда после этого может выглядеть, например, так:
cmake -H. -B.build -DBUILD_DEMO=On
Чтобы сделать такое действие в CLion, необходимо перейти в: Settings -> CMake -> CMake options.
Если используется Hunter (пакетный менеджер), то прописываются его настройки

include("tools/gate/cmake/HunterGate.cmake")                        # Подключение CMake скрипта с дополнительными функциями

HunterGate(
  URL "https://github.com/ruslo/hunter/archive/v0.23.214.tar.gz"    # URL к ядру Hunter
  SHA1 "e14bc153a7f16d6a5eeec845fb0283c8fad8c358"                   # SHA1 хэш
)
На этапе конфигурирования, CMake ожидает файл tools/gate/cmake/HunterGate.cmake.
Если этот файл не существует, возможны 2 варианта:

Необходимо добавить гит подмодуль:

git submodule add https://github.com/hunter-packages/gate.git tools/gate

Либо (если используется шаблонный репозиторий) необходимо обновить подмодули:

git submodule update --init --recursive
URL и SHA1 ядра Hunter можно получить в релизах: https://github.com/hunter-packages/gate.git
Название проекта

project(MyAwesomeProject)
Дополнительные опции для компилятора (могут отсутствовать)

string(APPEND CMAKE_CXX_FLAGS " -Wall -Werror")    # Флаги для включения всех предупреждений и дропа компиляции при их наличии
Подключение зависимых библиотек

Затем осуществляется подключение библиотек, в которых нуждается проект (Boost, GTest, Threads и т.д.)
Указания для Hunter о необходимо коллекционирования указанных пакетов
hunter_add_package(GTest)                              # Указание Hunter о добавлении пакета GTest
hunter_add_package(Boost COMPONENTS filesystem regex)  # Указание Hunter о добавлении пакета Boost с указанными компонентами
Указания о том, какие пакеты будут использованы (ожидается их наличие)
find_package(GTest CONFIG REQUIRED)
find_package(Boost CONFIG REQUIRED filesystem regex)
find_package(Threads REQUIRED)
CONFIG - ключевое слово, показывающее маску названий конфигурационных файлов.
REQUIRED - обязательность подключения пакета (иначе - ошибка).
Подробнее о ключевых словах: https://cmake.org/cmake/help/v3.0/command/find_package.html
Добавление целей сборки

После настройки окружающией среды пишется информация о том, что ожидается получить в результате сборки
Исполняемый файл

add_executable(
  my_very_interesting_target                              # Название цели
  ${CMAKE_CURRENT_SOURCE_DIR}/path_to_cpp_file
  ${CMAKE_CURRENT_SOURCE_DIR}/path_to_another_cpp_file
)
Библиотека

add_library(
  my_very_interesting_target_library              # Название цели
  STATIC                                          # Тип библиотеки (SHARED или STATIC)
  ${CMAKE_CURRENT_SOURCE_DIR}/path_to_cpp_file
  ${CMAKE_CURRENT_SOURCE_DIR}/path_to_another_cpp_file
)
Подробнее о типах библиотеки: https://www.geeksforgeeks.org/difference-between-static-and-shared-libraries/
Указание директорий с заголовочными файлами

target_include_directories(
  target_name                           # Цель, при сборке которой учитываются указанные пути к заголовочным файлам
  PUBLIC                                # область видимости (PRIVATE, INTERFACE или PUBLIC)
  ${CMAKE_CURRENT_SOURCE_DIR}/include
)
Указание библиотек для линковки

target_link_libraries(
  target_name                         # Цель, к которой просходит линковка
  library_name                        # Библиотеки, которые линкуются к цели
)
Названия библиотек из Hunter, как правило, имеют вид LibraryName::ComponentName.
Данные о библиотеках из пакета, добавленного через find_package хранятся в переменных.
Например, для Threads: ${CMAKE_THREAD_LIBS_INIT}
Тестирование

Для сборки тестирования необходимо наличие:

Добавления пакета googletest (GTest в Hunter)
Цели для сборки исполняемого файла
Линковки gtest_main и gtest (GTest::main и GTest::gtest в Hunter) к цели
Включенного тестирования в конфигурационном файле

enable_testing()                            # Включение тестирования
add_test(NAME unit_tests COMMAND tests)     # При тестировании выполнится исполняемый файл tests

Можно добавлять несколько тестовых целей под разными названиями.
И даже с использованием разных фреймворков.
Для сборки и выполнения тестирования необходимо выполнить следующую команду (ожидается предварительное конфигурирование):
cmake --build .build --target test
Пример тела конфигурационного файла с тестированием:
# 1
hunter_add_package(GTest)
find_package(GTest CONFIG REQUIRED)
find_package(Threads)

# 2
add_executable(
  tests
  ${CMAKE_CURRENT_SOURCE_DIR}/tests/test.cpp
)

# 3
target_link_libraries(
  tests
  ${CMAKE_THREAD_LIBS_INIT}
  GTest::gtest
  GTest::main
)

# 4
enable_testing()
add_test(NAME unit_tests COMMAND tests)
Для удобства в CLion необходимо добавить конфигурацию сборки google test.
Coverage

Подготовка

Начало конфигурации. Как правило, его трогать не надо.
if (BUILD_COVERAGE)                                                    # Если активна опция сборки с покрытием
  set(ENABLE_COVERAGE ON CACHE BOOL "Enable coverage build." FORCE)    # Установка значения переменной ENABLE_COVERAGE
  list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")   # Дополнение возможных местоположений конфигурационных cmake файлов
  find_package(codecov)                                                # Нахождение пакета (ожидается существование файла cmake/FindCodecov.cmake)
Тело

Далее прописываются цели, которые будут проанализированы на процент покрытия.
add_coverage(my_awesome_and_very_interesting_target)
add_coverage(tests)
Заключение

Конец конфигурации. Как правило, не надо трогать.
  list(APPEND LCOV_REMOVE_PATTERNS "'${PROJECT_SOURCE_DIR}/tests/*'")   # Удаление файлов с тестами из анализа
  coverage_evaluate()                                                   # Вызов анализатора
endif ()
.travis.yml

Настройка окружения

Для начала необходимо настроить окружение. Как правило, это не надо трогать
os: linux             # ОС
sudo: required        # Необходимость прав sudo
language: "minimal"   # Языковой шаблон
services:
  - docker            # Необходимые сервисы
env:
  # Based on Ubuntu 18.04
  # GCC 7.3
  # clang 7
  # CMake 3.10
  # gcovr
  # jscpd
  # cpplint
  - DOCKER_IMAGE="rusdevops/bootstrap:cpp"          # Используется по умолчанию

  # Based on Alpine 3.10
  # GCC 8.3
  # CMake 3.14
  # gcovr
  # jscpd
  # valgrind
  # Hunter GTest v1.8.0 (cached)
  # Hunter Boost cached components: exception
  #                                 filesystem
  #                                 log
  #                                 regex
  #                                 system
# - DOCKER_IMAGE="toliak/bootstrap-cpp"             # Для использования снять комментарий

before_script:
  - docker pull $DOCKER_IMAGE                       # Предварительное скачивание образа
Работы

Далее необходимо указать jobs'ы, которые будет выполнять Travis.
Jobs содержит название и команды.
jobs:
  include:
    - name: "tests"       # Название
      script:             # Команды для исполнения
        - docker run -t -v $(pwd):/var/builder/ -w /var/builder --entrypoint ./scripts/tests.sh $DOCKER_IMAGE
    - name: "quality"
      script:
        - docker run -t -v $(pwd):/var/builder/ -w /var/builder --entrypoint ./scripts/duplication.sh $DOCKER_IMAGE
    # И так далее
Дополнительные настройки

К таким относятся, например, правила для веток и для уведомлений.
Например:
notifications:
  email: false