В прошлой статье я подробно описал разные способы сборки и установки библиотеки com_ports. Сегодня поговорим о том, как собрать своё приложение, которое будет её использовать. Начнем мы со сборки примеров, входящих в состав библиотеки, а потом напишем полностью своё приложение.

Важно: информация приводимая в этой статье актуальна на 3 сентября 2026 года. Изменения, внесенные в библиотеку com_ports после этой даты, могут быть не отражены в статье.

В состав библиотеки com_ports уже входит три примера её использования. Все они находятся в подкаталоге examples корневого каталога библиотеки (в нём находится списковый файл CMakeLists.txt библиотеки). Собрать эти примеры можно как во время сборки самой библиотеки, так и отдельно от неё. Во втором случае собираемые примеры будут компоноваться (линковаться) с библиотекой com_ports, ранее установленной в системе.

Рассмотрим все эти случаи отдельно.

Сборка примеров совместно с библиотекой

Совместная сборка осуществляется с помощью опции COM_PORTS_BUILD_EXAMPLES. Ниже приводится возможная последовательность команд.

cmake -S . -B build -DCOM_PORTS_BUILD_EXAMPLES=ON
cmake --build build

Обе эти команды и используемые в них флаги описывались в прошлой статье [1].

Если всё сделано правильно, то в текущем каталоге сборки будет создан подкаталог examples. А в нём — подкаталоги, содержащие скомпилированные примеры использования библиотеки.

Для сборки примеров отдельно от библиотеки последняя должна быть предварительно скомпилирована и установлена в систему [1]. Возможны два случая.

1. Библиотека установлена по пути известному CMake.
2. Библиотека установлена по пути неизвестному CMake.

Ниже мы рассмотрим оба этих случая.

Также нужно помнить о возможной ошибке компоновки в том случае, если библиотека и пример собираются в разной конфигурации. Например, установленная библиотека была собрана в конфигурации Debug, а пример — в Release. Для решения этой проблемы нужно использовать флаг --config. Более подробная информация об этой проблеме и флаге --config приводилась в прошлой статье [1].

Отдельная сборка примеров. Случай 1

Для сборки примера перейдите в каталог этого примера, содержащий списковый файл CMakeLists.txt, и выполните в нём уже известные нам команды:

cmake -S . -B build
cmake --build build

Если всё сделано правильно, то в подкаталоге build (или в одном из его подкаталогов в зависимости от используемой системы сборки) будет находиться скомпилированный файл примера с расширением exe.

Отдельная сборка примеров. Случай 2

Если библиотека com_ports была установлена в какой-либо пользовательский каталог, то CMake может её не найти. В этом случае конфигурирование примера завершится ошибкой. Ниже приводится пример сообщения об ошибке.

CMake Error at C:/Users/Sergey/Documents/projects/cpp/com_ports/cmake/build_example.cmake.in:23 (find_package):
  By not providing "Findcom_ports.cmake" in CMAKE_MODULE_PATH this project
  has asked CMake to find a package configuration file provided by
  "com_ports", but CMake did not find one.

  Could not find a package configuration file provided by "com_ports"
  (requested version 1.0.0) with any of the following names:

    com_portsConfig.cmake
    com_ports-config.cmake

  Add the installation prefix of "com_ports" to CMAKE_PREFIX_PATH or set
  "com_ports_DIR" to a directory containing one of the above files.  If
  "com_ports" provides a separate development package or SDK, be sure it has
  been installed.

В этом же сообщении CMake подсказывает нам, как исправить ошибку. Нам нужно с помощью переменной CMAKE_PREFIX_PATH [2] указать каталог, в который ранее была установлена библиотека com_ports. Тогда команды сборки примут вид:

cmake -S . -B build -DCMAKE_PREFIX_PATH=../../install_dir
cmake --build build 

В этом примере «../../install_dir» — это относительный путь к каталогу, в который ранее была установлена библиотека com_ports. У Вас он, скорее всего, будет другим.

Разбор спискового файла примера

Каждый пример имеет свой списковый файл. Но они мало чем отличаются друг от друга. Ниже приводится содержимое спискового файла для примера exception.

cmake_minimum_required(VERSION 3.15)

set(EXAMPLE_NAME exception_example)

project(${EXAMPLE_NAME} LANGUAGES CXX)

include("../../cmake/build_example.cmake.in")

В первой строке вызывается функция cmake_minimum_required [3]. Она устанавливает минимально допустимую версию утилиты CMake для проекта (примера). В нашем случае минимальная версия — 3.15.

В третьей строке объявляется переменная EXAMPLE_NAME. Ей присваивается значение exception_example [4]. Вообще, единственное чем отличаются списковые файлы примеров друг от друга это значением переменной EXAMPLE_NAME.

В пятой строке объявляется сам проект [5]. Здесь указывается, что проект имеет имя, заданное в переменной EXAMPLE_NAME, и что проект написан на языке C++. Как говорится в статье «CMake и C++ — братья навек» [6], CMake по умолчанию ищет два компилятора: для языка С и для языка C++. С помощью опции LANGUAGES мы указываем, что нам нужен только компилятор для языка C++. Компилятор для языка C нам не нужен.

В седьмой строке мы загружаем и выполняем содержимое файла build_example.cmake.in [7]. Именно в нём находится вся основная логика по сборке примеров.

Разбор файла build_example.cmake.in

Файл build_example.cmake.in мы будем разбирать по частям. С его полным содержимым можно ознакомиться в репозитории библиотеки com_ports [8].

set(CMAKE_CXX_STANDARD 17)

Указываем, что для сборки нашего приложения необходим стандарт C++17 [9].

set(CMAKE_CXX_STANDARD_REQUIRED ON)

Указываем, что требование стандарта C++17 является обязательным. Без установки переменной CMAKE_CXX_STANDARD_REQUIRED в значение истина, CMake может использовать при сборке более старый стандарт, так как воспринимает значение переменной CMAKE_CXX_STANDARD как рекомендацию, а не как жесткое требование [10].

set(CMAKE_CXX_EXTENSIONS OFF)

Отключаем все расширения компилятора [11]. Так мы защищаем себя от использования расширений компилятора, которые могут привести к проблемам при переносе приложения на другой компилятор.

if(MSVC)
    add_compile_options(/W4 /WX)
endif()

Проверяем использование компилятора от компании Microsoft [12]. Если это так, то устанавливаем флаги компилятора: /W4 (максимальный уровень предупреждений) и /WX (воспринимать предупреждения компилятора как ошибки) [13]. Для установки флагов компилятора используется функция add_compile_options [14].

if(CMAKE_CXX_COMPILER_ID MATCHES "^(GNU|Clang)$")
    add_compile_options(-Wall -Wextra -pedantic -Werror)
endif()

Здесь делается тоже самое, что и в предыдущей части но для компиляторов GCC и Clang.

К сожалению для компиляторов GCC и Clang нет отдельной переменной (по аналогии с MSVC) поэтому пришлось использовать переменную CMAKE_CXX_COMPILER_ID [15] для получения идентификатора компилятора и функцию MATCHES [16] для сравнения полученного идентификатора с ожидаемыми типами компиляторов.

add_executable(${EXAMPLE_NAME} main.cpp)

Объявляем, что в результате сборки нашего проекта должен получиться исполняемый файл с именем, хранящимся в переменной EXAMPLE_NAME [17]. Как Вы помните, эта переменная была объявлена в списковом файле примера, в который загружается разбираемый нами файл build_example.cmake.in.

Также здесь указывается, что проект состоит всего из одного файла с исходными текстами main.cpp.

string(COMPARE EQUAL "${CMAKE_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}" is_top_level)

Сравниваем переменные CMAKE_SOURCE_DIR [18] и CMAKE_CURRENT_SOURCE_DIR [19] друг с другом. Если их значения равны друг другу, то в переменную is_top_level будет записано значение истина, в противном случае — ложь. Зачем это нужно?

Как Вы уже видели, примеры могут собираться во время сборки библиотеки com_ports и отдельно от неё. Мне нужно как-то различать эти ситуации. Для этого и будет использоваться переменная is_top_level.

Разница между переменными CMAKE_SOURCE_DIR и CMAKE_CURRENT_SOURCE_DIR хорошо объясняется в обсуждении на StackOverflow [20]. В нём говорится:

CMAKE_SOURCE_DIR is where cmake was originally invoked, and CMAKE_CURRENT_SOURCE_DIR is where cmake is currently working. For instance, if you use add_subdirectory command to include a dependency to your project, the dependency will have its own CMAKE_CURRENT_SOURCE_DIR but CMAKE_SOURCE_DIR will remain the same.

или в моём переводе на русский язык:

CMAKE_SOURCE_DIR содержит каталог, в котором был вызван CMake. CMAKE_CURRENT_SOURCE_DIR — каталог, в котором CMake работает в настоящее время. Например, если вы используете команду add_subdirectory для добавления зависимости к вашему проекту, добавленная зависимость будет иметь своё значение CMAKE_CURRENT_SOURCE_DIR, но значение CMAKE_SOURCE_DIR будет тем же, что и у основного проекта.

При сборке примеров совместно с библиотекой com_ports, первые добавляются в основной проект библиотеки с помощью функции add_subdirectory [21]. Поэтому мы и видим разницу в значениях переменных CMAKE_SOURCE_DIR и CMAKE_CURRENT_SOURCE_DIR.

Синтаксис используемой команды сравнения строк можно посмотреть в документации CMake [22].

Этот приём с переменной is_top_level я позаимствовал из статьи Антона Пантюхина «Руководство по CMake для разработчиков C++ библиотек» [23] (раздел «Определение проекта»).

if(is_top_level)
    find_package(com_ports 1.0.0 REQUIRED)
    target_link_libraries(${EXAMPLE_NAME} com_ports::com_ports)
else()

Если значение переменной is_top_level равно истина, значит пример собирается независимо от библиотеки. В этом случае библиотека должна быть установлена в системе. Для её поиска вызывается функция find_package [24]. В параметрах этой функции указывается, что нужно найти пакет com_ports версии 1.0.0 (или совместимой с этой версией). Ключевое слово REQUIRED говорит о том, что пакет com_ports обязательно должен быть найден. Если он не найден, то произойдет ошибка конфигурирования.

После того как пакет com_ports найден, с помощью функции target_link_libraries [25] указывается, что собираемый пример должен быть скомпонован (слинкован) с найденной библиотекой com_ports.

else()
    target_include_directories(${EXAMPLE_NAME} PRIVATE
        "${CMAKE_BINARY_DIR}/include")
    target_link_directories(${EXAMPLE_NAME} PRIVATE "${CMAKE_BINARY_DIR}")
    target_link_libraries(${EXAMPLE_NAME} com_ports)
endif()

#include <com_ports/com_ports.hpp>

#include <iostream>

int main()
{
    std::wcout << L"COM ports:\n\n";

    auto ports = com_ports::get_names();

    for(const auto &port : ports)
        std::wcout << port << L'\n';

    return 0;
}

cmake_minimum_required(VERSION 3.15)

project(my_project)

add_executable(my_project main.cpp)

find_package(com_ports REQUIRED)

target_link_libraries(my_project com_ports::com_ports)

cmake -S . -B build
cmake --build build --config Release

>.\build\Release\my_project.exe
COM ports:

COM3
COM4

cmake -S . -B build -DCMAKE_PREFIX_PATH=../com_ports/install_dir
cmake --build build --config Debug

cmake_minimum_required(VERSION 3.15)

project(my_project)

add_executable(my_project main.cpp)

list(APPEND CMAKE_PREFIX_PATH "../com_ports/install_dir")

find_package(com_ports REQUIRED)

target_link_libraries(my_project com_ports::com_ports)

cmake -S . -B build
cmake --build build --config Debug

all: main.exe

main.exe: main.cpp
	cl main.cpp /EHsc /MDd /I "../com_ports/install_dir/1.0.0/include" /link /LIBPATH:"../com_ports/install_dir/1.0.0/lib" com_ports.lib advapi32.lib setupapi.lib

nmake

all: main.exe

main.exe: main.cpp
	g++ main.cpp -o main.exe -I"../com_ports/install_dir/1.0.0/include" -L"../com_ports/install_dir/1.0.0/lib" -lcom_ports -lsetupapi

make