Cmake install prefix windows

cmake_minimum_required() —

Alternative Methods to cmake_minimum_required in CMake

It ensures that the build system has the features and compatibility required by the project’s build instructions.This command specifies the minimum required version of CMake that is necessary to build the project

file() —

Alternatives to ‘file()’ Command for File Manipulation in CMake

file(TIMESTAMP filename variable [format] [UTC]): This retrieves the timestamp (modification time) of the file and stores it in a variable

add_definitions() —

CMake add_definitions(): A Deep Dive into Preprocessor Macro Management

Influence Compilation Behavior These macros can significantly affect how your code is compiled, enabling features like: Conditional Compilation Control which parts of your code are included or excluded based on the defined macros

find_path() —

Beyond find_path(): Alternative Methods in CMake

Locates executable files find_path() is primarily used to find the full path to an executable file within the system. This is crucial when your CMake project needs to:

add_custom_command() —

Beyond add_custom_command(): Exploring CMake Alternatives

It’s highly versatile and lets you execute arbitrary commands during the build process.add_custom_command() is a crucial CMake command that allows you to define custom build steps that don’t fit the standard target-based approach

FetchContent —

Improving CMake Builds with FetchContent: Best Practices and Tips

Key Benefits Simplified Dependency Management No need to manually download, extract, and configure external libraries. FetchContent handles the entire process

cmake_path() —

Alternatives to cmake_path() in CMake Projects

It deals with paths in the format of the build system (the host platform where you’re running CMake), not the target system (where your compiled code will run)

Вступление

Популярность CMake растёт. Многие крупные проекты переходят с собственных инструментов для сборки на CMake. Проект Conan предлагает интеграцию с CMake для управления зависимостями.

Разработчики CMake активно развивают инструмент и добавляют новые функции, решающие общие проблемы, возникающие при сборке проектов. Переход с CMake 2 на CMake 3 был достаточно болезнен. Документация не покрывает все аспекты использования. Функционал крайне обширен, а возникающие трудности различаются от проекта к проекту. В статье я расскажу о инструментах, которые предлагает CMake 3.10 и выше. В каждой новой версии появляются новые детали или улучшаются старые. Об актуальном состоянии лучше проанализировать Changelog, так как многие улучшения последних версий весьма специфичны для отдельных проектов, как например улучшение поддержки Cuda компиляторов. Я же сфокусируюсь на общих понятиях, которые помогут организовать проект на С++ оптимальным образом с точки зрения использования CMake как основной системы сборки.

CMake предлагает широкий набор инструментов. Чтобы не потеряться в определениях, в статье сперва будут определены сущности, через которые будут объяснены конкретные примеры. Названия сущностей я продублирую на английском. Некоторые термины не имеют однозначного перевода на русский язык.

Обзор демонстрационного проекта

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

Проект написан на С++, предполагает кросс-платформенность. Содержит переиспользуемые компоненты и зависит от внешних библиотек. Предполагаемая область использования — интеграция в конечное приложение, выполняющее анализ видеопотока, поэтому проект также содержит демонстрационное приложение с примером использования API. Демо-приложение поставляется в исходных кодах вместе с двоичной библиотекой.

Структура файлов и папок проекта с именем ‘neuon’ следующая:

neuon
|-sources
  |-res
  |-src
  |-CMakeLists.txt
|-headers
  |-include
  |-CMakeLists.txt
|-examples
  |-res
  |-src
  |-CMakeLists.txt
|-cmake
  |-FindTensorflow.cmake
  |-FindJsonCpp.cmake
|-res
	|-neoun-config.cmake.in
|-CMakeLists.txt

Используемые сущности и понятия

• Приложения в комплекте поставки (CMake, CPack, CTest, CDash)

• Предопределенные и ожидаемые файлы и их назначение

• Модули, конфигурации

• Объектная модель скриптов — цели, свойства

• Свойства, переменные, аргументы и параметры.

Приложения в комплекте поставки (CMake, CPack, CTest, CDash)

CMake поставляет в комплекте с несколькими приложениями, предназначенными для дополнения процесса сборки проекта. За саму сборку отвечает cmake, который работает с файлом, описывающим проект. Использование cmake состоит из нескольких шагов: шаг генерации(generation), шаг сборки(build) и шаг установки(install).

Первым этапом при сборке проекта необходимо сгенерировать скрипты сборки, используя описание проекта(CMakeLists.txt) на языке CMake. Результатом генерации является скрипт или набор файлов, необходимый для запуска нижележащей системы сборки(например Makefile или VIsual Studio Solution). CMake не выполняет запуск компилятора сам, хотя может быть использован как прокси для обобщения вызовов нижележащих инструментов.

Следующим шагом происходит непосредственно сборка проекта из исходного кода. Результатом являются бинарные файлы и другие артефакты, являющиеся частью конечного продукта для потребителя. Все артефакты, несмотря на свою доступность, находятся в специальном состоянии, контролируемом CMake и как правило непригодны к перемещению или распространению, однако, могут быть использованы для отладки локально.

Финальным шагом использования СMake является шаг установки. Установка подразумевает пересборку либо по необходимости перелинковку бинарных артефактов с целью сделать их пригодными к использованию на целевой системе. Как правило, при установке также происходит перемещение артефактов в желаемые расположения и создании желаемой раскладки по директориям. Установка на этом этапе не имеет ничего общего с установкой дистрибутива или распаковкой архива, но при некорректной конфигурации сборки может установить свежесобранные артефакты в локальную систему. При использовании шаг установки не выполняется вручную.

Базовый функционал CMake не заканчивается на консольном приложении. CMake также предоставляет графический интерфейс для управления этапами генерации и сборки — cmake-gui. А также предлагает широкий набор модулей(CMake modules) для использования в файлах описания проекта. Посторонние проекты могут предлагать свои конфигурации(Library Configs) для упрощения использования в связке с CMake.

CMake крайне гибкий и расширяемый инструмент. И цена за это — его перегруженность. Если проекту нужен какой-то функционал при сборке — имеет смысл изучить, что предлагает СMake. Может быть такая же проблема уже была решена и решение прошло проверку сообществом.

Приложение CTest расширяет возможности по сборке путем предоставления единого интерфейса по взаимодействию с тестами. Если проект содержит тесты, ctest играет роль единого запускающего механизма, формирующего отчет по запуску. Для использования CTest как универсального исполнителя каждый тест должен быть зарегистрирован. Согласно его регистрации, в финальный отчет попадет имя и результат выполнения теста. CTest также обеспечивает интеграцию с CDash — панелью общего доступа к результатам запусков тестов, с управлением запусками, группировкой тестов и прочим функционалом, использующимся в автоматизированный конвейерах сборки. (CI/CD Dashboard).

CPack — это инструмент упаковки скомпилированного проекта в платформо-зависимые пакеты и установщики. CPack c одной стороны универсален для создания установщиков целевого формата, с другой стороны зависит от системы, где запускается, так как полагается на системные инструменты для создания установщика. Единый формат командной строки для генерации NSIS установщика для Windows, DEB пакета для Ubuntu и RPM пакета для Centos не подразумевает генерацию RPM при запуске на Ubuntu или Windows. Основным преимуществом CPack перед отдельными упаковщиками является то, что вся конфигурация установщика находится рядом с проектом, и использует те же механизмы, что и сам CMake. Для добавления нового формата в проект достаточно доопределить формато-специфичные переменные и CPack сделает остальную работу.

Предопределенные и ожидаемые файлы и их назначение.

CMake широко использует файловую систему и управляет многими папками и файлами. CMake поддерживает сборку вне расположения проекта. Местоположение проекта называется исходной папкой( Source Directory). При генерации CMake сохраняет файлы в папку сборки (Build Directory). В некоторых контекстах папка сборки также именуется папкой бинарных артефактов(Binary Directory), как противопоставление исходной папке. При выполнении шага установки начинает фигурировать директория установки(Install directory). Эти местоположения могут указывать в одно место, или в разные — это контролируется независимо и доступно при использовании.

Помимо непосредственно файловой системы, CMake использует механизм префиксов для гибкой настройки относительных путей. Префикс установки((CMAKE_INSTALL_PREFIX)) определяет префикс, который будет использоваться для всех относительных путей, используемых проектом после установки. . Префикс установки и директория установки могут быть одинаковы. Но могут и различаться, что используется для кросс-компиляции или создания переносимых артефактов, не привязанных к конкретному местоположению. Префикс-путь (CMAKE_PREFIX_PATH) имеет особенный смысл для шага генерации. Как гласит документация, это список путей, которые СМаке использует в дополнение к своему местоположению как корневую папку для поиска модулей и расширений. При необходимости указать дополнительные места, используется префикс-путь. Он не влияет на результат сборки, однако крайне важен для поиска зависимостей, интеграции со сторонними библиотеками и использования модулей, не входящих в комплект поставки CMake либо являющихся частью проекта.

CMake использует некоторые предопределённые имена или части имени файла, наделяя эти файлы особенным смыслом.

Поддержка CMake в проектах обеспечивается CMakeLists.txt файлом, обычно расположенным в корне проекта. Этих файлов может быть несколько и они могут быть включены друг в друга различными способами. Основная идея этого файла — он предоставляет главную точку входа для CMake и описание проекта начинается с него.

В папке сборки после генерации можно найти файл CMakeCache.txt. Этот файл содержит полное представление всего проекта, которое CMake смог разобрать и сгенерировать. Этот файл может быть отредактирован вручную, для изменения некоторых параметров и переменных. Однако, при следующей генерации изменения могут быть утеряны, если параметры и аргументы запуска CMake утилиты изменились.

Файлы, имена которых регистро-зависимо оканчиваются на Config.cmake или -config.cmake, являются файлами CMake совместимой конфигурации библиотек и зависимостей. (CMake config files). Эти файлы как правило распространяются вместе с библиотеками и обеспечивают интеграции библиотек в проекты использующие CMake для сборки.

Файлы, имена который выглядят как Find*.cmake , содержат CMake модули(CMake modules). Модули расширяют функционал CMake, и используются в CMakeLists.txt для выполнения рутинных задач. Модули следует использовать как фреймворк или библиотеку функций при написании своего CMakeLists.txt

Другие файлы с расширением .cmake предполагают произвольное содержимое написанное с использованием CMake скриптового языка. Проекты включают такие файлы в целях переиспользования частей скриптов.

Иногда в CMake проектах могут встретиться файлы с расширением .in или .in.in Таким образом могут именоваться шаблоны файлов, которые инстанцируются CMake при генерации. Инстанцированные файлы, затем используются проектом как текстовые артефакты, либо как файлы, актуальные в момент генерации и сборки. Например они могут содержать в себе версии и дату сборки бинарных артефактов, или шаблон CMake конфигурации, которая будет распространятся с артефактами позже.

Модули, конфигурации

CMake Модули и CMake конфигурации содержат в себе код на CMake скрипте. Несмотря на схожесть, это разные по назначению сущности. Модули, обычно расширяют поведение CMake, предоставляя функции, макросы и алгоритмы для использования в CMakeLists.txt, поставляются в комплекте с CMake, именуются как Find*.cmake и располагаются в CMAKE_PREFIX_PATH. Модули не привязаны к конкретному проекту и должны быть проектно-независимы. Проект может дополнять список модулей по необходимости при генерации или при использовании, но рекомендуется публиковать модули с целью включить их в состав дистрибутива CMake. Модули играют роль «Стандартной библиотеки CMake». Модули поддерживаются и разрабатываются мейнтейнерами CMake.

Конфигурации же напротив, неотъемлемая часть проекта, поставляются вместе с заголовочными файлами и библиотеками импорта, и обеспечивают интеграцию библиотек в другие проекты. Конфигурация проекта не используется при сборке проекта. Конфигурация является результатом сборки проекта и входит в установщик, поддерживаются и разрабатываются авторами проекта.

Конфигурации не должны располагаться в CMAKE_PREFIX_PATH и должны следовать соглашению о местоположении и именовании, описанном в официальной документации. (https://cmake.org/cmake/help/latest/command/find_package.html#full-signature-and-config-mode)

Конфигурации описывают зависимости проекта, с целью облегчить его использование. Конфигурации крайне чувствительны к своей реализации. Следование практикам и рекомендациям поможет делать конфигурации, которые облегчают интеграции проекта заказчикам и пользователям.

Объектная модель скриптов — цели, свойства

Начиная с версии 3 CMake сместил парадигму своих скриптов с процедурно-ориентированной на объекто-ориентированную. В версии 2, описание проекта содержало набор вызовов функций, которые выполняли настройку свойств, необходимых для сборки и использования. В версии 3, на смену переменным и свойствам пришли цели. Цель(target) в контексте CMake, это некоторая сущность, над которой можно выполнять операции, изменять ее свойства, обеспечивать ее доступность и готовность. Целями могут являются, но не ограничиваются, бинарные артефакты и исполняемые файлы проекта, заголовочные файлы проекта, дополнительные файлы, создаваемые при генерации, зависимости целей, внешние библиотеки или файлы и т.д.

У целей есть свойства(properties), которые могут быть доступны как для чтения(все из них), так и для записи(многие), с целью тонкой настройки и обеспечения желаемого результата. Свойства — это именованные поля целей. Управляются CMake на основе дефолтных значений параметров и аргументов и\или окружения сборки, а также управляются сами проектом, в зависимости от назначения и желаемого результата.

Свойства, переменные, аргументы и параметры.

CMake обеспечивает гибкость настройки и использования предоставляя разные способы контроля и управления своим поведением.

Цели можно контролировать их свойствами. Командная строка при запуске CMake утилит может содержать аргументы командной строки(arguments), передаваемые напрямую в утилиту общепринятым способом --argument или -f lag . В командной строке также могут встречаться параметры(parameters). Параметры, передаваемые в командной строке через -DNAME=VALUE или -DNAME:TYPE=VALUE преобразуются в переменные(variables) с тем же именем в теле скрипта. Также параметрами могут являться переменные окружения или некоторые вхождения CMake переменных в файле CMakeCache.txt. Параметры от переменных в CMakeCache.txt практически ничем не отличаются.

CMake переменные — это переменные в общепринятом смысле слова при написании скриптов. Переменные могут быть объявлены или не быть объявлены. Могут иметь значение или не иметь значение, или иметь пустое значение. Помимо переменных унаследованных от параметров(или значений по умолчанию), в скриптах можно объявлять и использовать свои собственные переменные.

Таким образом, управление CMake утилитами выполняется через аргументы командной строки, параметры запуска, переменными в скриптах, и свойствами целей. Аргументы не оказывают влияние на состояние скриптов, параметры превращаются в переменные с тем же именем, свойства целей имеют предустановленное документированное имя и могут быть установлены в произвольные значения через вызов соответствующих функций.

Примеры задач и использование доступных инструментов

У меня в руках проект, который использует CMake. Что с ним делать?

Сгенерировать сборочные файлы в папке сборки, запустить сборку, опционально запустить установку.

cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release -Sneuon -Bcmake-release-build
cmake --build cmake-release-build -- -j8
cmake --build cmake-release-build --target install

В этом примере мы собираем релизную сборку проекта в отдельной директории. Релиз в данной ситуации подразумевает включение оптимизаций и удаления отладочной информации из бинарного артефакта. CMake имеет 5 известных значений CMAKE_BUILD_TYPE параметра: Debug, Release, RelWithDebInfo, MinSizeRel и None — если не установить конкретное значение. Также мы явно указываем CMAKE_INSTALL_PREFIX /usr/local является значением по умолчанию для Unix систем, а так как запись в эту директорию требует прав суперпользователя, то последняя команда установки вернет ошибку так как не сможет записать файлы по назначению. Следует либо запустить её с правами суперпользователя(что крайне не рекомендуется, если целевая платформа имеет пакетные менеджеры), либо сменить префикс установки в место, не требующее прав суперпользователя, либо не устанавливать проект в систему, либо установить его с использованием переназначения назначения. Для make как нижележащей системы можно использовать DESTDIR: cmake --build cmake-release-build --target install -- DESTDIR=$HOME/neuon

Переназначение назначения зависит от собственно системы сборки и не каждая из них умеет такое делать.

Пример сборки под Linux из реального проекта:

# Локальная сборка зависимости проекта и установка в отдельную директорию, 
# которая будет использоваться при сборке основного проекта.CMake автоматически собирает проект
# при установке по необходимости.
cmake -DCMAKE_POSITION_INDEPENDENT_CODE=On -DCMAKE_INSTALL_PREFIX=/opt/neuon -DCMAKE_BUILD_TYPE=Release -s googletest -Bgoogletest-build
cmake --build googletest-build --target install -- DESTDIR=$PWD/deps -j8

# Сборка и упаковка в TGZ основного проекта в 8 потоков make.
cmake -DCMAKE_PREFIX_PATH=$PWD/deps -DCMAKE_INSTALL_PREFIX=/opt/neuon -DCPACK_SET_DEST_DIR=On -DCMAKE_BUILD_TYPE=Release -Dversion=0.0.0 -S neuon -B neuon-build
cmake --build neuon-build -- -j8
cd neuon-build && cpack -G "TGZ" 
# CPack на конец 2020 не поддерживает -B аргумент. Необходимо запускать в папке сборки

Для генерации под Windows, используя Visual Studio:

cmake -G "Visual Studio 16 2019" -A x64 -T host=x64 -DBUILD_SHARED_LIBS=On -DCMAKE_PREFIX_PATH=d:\msvc.env\ -DCMAKE_INSTALL_PREFIX=/neuon -DFFMPEG_ROOT=d:\msvc.env\ffmpeg -S neuon -B neuon-build

Как запустить тесты с CTest?

После генерации запустить CTest в папке сборки.

ctest .

По умолчанию, CTest не выводит ход выполнения тестов. Аргументы вызова помогут достигнуть желаемого поведения.

Как пользоваться целями и свойствами?

add_library(neuon
    ${CMAKE_CURRENT_BINARY_DIR}/generated/version.cpp
    ${CMAKE_CURRENT_BINARY_DIR}/generated/birthday.cpp
    src/license.cpp
    src/model.cpp
    src/tensorflow_api.cpp
    src/tensorflow_dynamic.cpp
    src/tensorflow_static.cpp
    src/neuon_c.cpp
    src/neuon_cxx.cpp
    src/demo.cpp
    src/configuration.cpp
    src/speech_detection.cpp
    src/face_detection.cpp
    src/log.cpp
    )
add_library(neuon::neuon ALIAS neuon)
target_link_libraries(neuon PRIVATE Threads::Threads JsonCpp::JsonCpp Boost::headers Aquila::Aquila dlib::dlib Tensorflow::Tensorflow Boost::filesystem spdlog::spdlog PUBLIC neuon::headers )
target_compile_features(neuon PRIVATE cxx_std_17)
set_target_properties(neuon PROPERTIES CXX_EXTENSIONS OFF)
set_target_properties(neuon PROPERTIES INSTALL_RPATH "$ORIGIN")
set_target_properties(neuon PROPERTIES C_VISIBILITY_PRESET hidden)
set_target_properties(neuon PROPERTIES CXX_VISIBILITY_PRESET hidden)
set_target_properties(neuon PROPERTIES VISIBILITY_INLINES_HIDDEN On)
target_compile_definitions(neuon PRIVATE BOOST_UBLAS_INLINE= NEUON_ORIGINAL_BUILD )
target_include_directories(neuon
    PRIVATE src/
    ../depends/sdk/src
    ${CMAKE_CURRENT_BINARY_DIR}/generated
    )

install(TARGETS neuon EXPORT neuon-library
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT devel
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT devel NAMELINK_COMPONENT devel
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} COMPONENT runtime
    OBJECTS DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT devel
    INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
    )
install(EXPORT neuon-library NAMESPACE neuon:: DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/neuon/cmake FILE neuon-targets.cmake COMPONENT devel)
install(FILES res/model.pb res/normale.json res/shape_predictor_68_face_landmarks.dat DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/neuon/res COMPONENT runtime)

Добавляем цель сборки — библиотеку. Не указываем тип библиотеки — разделяемая или статическая, оставляя на усмотрение собирающего. Наш конвейер сборки может собирать два варианта двумя разными вызовами генерации. Затем добавляем цель-псевдоним, это позволяет использовать пространство имен в CMake конфигурации проекта для более выразительного именования зависимостей. Цель-псевдоним используется тут же в проекте демо-приложением, которое при этом умеет использовать и файл конфигурации. Использование пространства имен в файле конфигурации поместит все цели в него. Без псевдонима, демо-приложение должно будет явно отличать связываться с целью родительского проекта, или с целью из конфигурации.

Указываем список библиотек и других зависимостей, с которыми необходимо линковать нашу библиотеку, и выставляем различные свойства, влияющие на параметры компиляции. В последней части, указываем как именно мы хотим устанавливать нашу библиотеку — установка цели описывается через введение экспортируемой сущности, для которой прописываются свойства, такие как папка назначения в зависимости от конкретного типа файла или типа цели или компонент для разделения установщиков на отдельные пакеты или наборы устанавливаемых файлов. Затем указывается установка экспортируемой сущности с указанием пространства имен для используемых целей.

И напоследок несколько файлов устанавливаются как есть. Это ресурсы, которые распространяются как часть проекта.

Как использовать файлы конфигурации?

Начиная с CMake 3.0 рекомендуется в файлах конфигурации объявлять цели, которые могут быть использованы потребителем. До CMake 3.0 файлы конфигурации объявляли несколько переменных, именованных по определенным правилам и эти переменные становились доступны потребителю. На настоящий момент, некоторые проект до сих пор используют только старый подход, некоторые проекты используют старый подход как дополнение к новому. Иногда появляются инициативы завернуть старые конфигурации в новые или в CMake модули. В этом примере мы уделяем внимание новому подходу, как рекомендуемому.

find_package(FFMPEG REQUIRED COMPONENTS avcodec avformat swscale swresample)

if(NOT TARGET neuon::neuon)
    find_package(Neuon REQUIRED COMPONENTS headers neuon)
endif()

add_executable(neuon-sample
    ${CMAKE_CURRENT_BINARY_DIR}/generated/version.cpp
    ${CMAKE_CURRENT_BINARY_DIR}/generated/birthday.cpp
    src/neuon_sample.cpp
    depends/sdk/src/extraction.cpp
    depends/sdk/src/options.cpp
    depends/sdk/src/source.cpp
    depends/sdk/src/demuxer.cpp
    depends/sdk/src/decoder.cpp
    depends/sdk/src/interruption.cpp
    depends/sdk/src/track_adapter.cpp
    depends/sdk/src/access_unit_adapter.cpp
    depends/sdk/src/resample.cpp
    )
target_link_libraries(neuon-sample PRIVATE spdlog::spdlog Threads::Threads Boost::program_options FFMPEG::avcodec FFMPEG::avformat FFMPEG::swscale FFMPEG::swresample neuon::neuon)
target_compile_features(neuon-sample PRIVATE cxx_std_11)
set_target_properties(neuon-sample PROPERTIES CXX_EXTENSIONS OFF)
target_include_directories(neuon-sample
    PRIVATE src/
    depends/sdk/src
    ${CMAKE_CURRENT_BINARY_DIR}/generated
    )

find_package ищет файлы конфигурации, руководствуясь предопределенными правилами разрешения путей. Если этот CMakeLists.txt не включен в основной проект, то neuon::neuon цель будет недоступна и нам требуется явно подключить библиотеку штатным способом. В обратном случае — цель-псевдоним обеспечит нам идентичный функционал и наше приложение будет слинковано с библиотекой из той же директории сборки.

Мы заранее ввели цель-псевдоним в основном проекте библиотеки для универсальности нашего CMakeLists.txt в проекте демо-приложения. Теперь при сборке нашего демо-приложения как части сборки проекта — будет использоваться цель-псевдоним, а при сборке пользователем наша библиотека будет доступна через имя определенное в конфигурации, дополненное пространством имён.

Как добавить свои тесты в запуск CTest?

enable_testing()

find_package(GTest 1.8 CONFIG REQUIRED COMPONENTS gtest gmock gmock_main )
include(GoogleTest)

add_executable(ut_curl test/ut_curl.cpp src/curl.cpp)
target_link_libraries(ut_curl PRIVATE GTest::gmock GTest::gmock_main CURL::libcurl)
target_include_directories(ut_curl PRIVATE src/)

add_test(test_of_curl_wrapper ut_curl)

enable_testing() указывает CMake, что планируется использование CTest. add_test() регистрирует исполняемый файл, собираемый в проекте как один из тестов для запуска. Тестом может быть любая исполняемая сущность — приложение, скрипт, сторонний инструмент. CTest опирается на код возврата для определения пройден тест или нет и формирует соответственный отчет.

enable_testing()
find_package(GTest 1.8 CONFIG REQUIRED COMPONENTS gtest gmock gmock_main )
include(GoogleTest)

add_executable(ut_curl test/ut_curl.cpp src/curl.cpp)
target_link_libraries(ut_curl PRIVATE GTest::gmock GTest::gmock_main CURL::libcurl)
target_include_directories(ut_curl PRIVATE src/)
gtest_discover_tests(ut_curl)

CMake предлагает готовый модуль для работы с Google Test Framework. Если ваши тесты используют Googletest, то в исполняемом файле обычно множество юнит-тестов. Регистрация штатным способом не даст полной картины запуска юнит-тестов, так как с точки зрения CMake — одно приложение, один тест. include(GoogleTest) подключает стандартный модуль, который содержит функцию gtest_discover_tests, которая регистрирует все тесты из собранного тестового приложения как отдельные тесты в CTest. Отчет становится гораздо более информативным.

Как конфигурировать CPack?

include(CPackComponent)

cpack_add_component(runtime)
cpack_add_component(devel DEPENDS runtime)
cpack_add_component(sample DEPENDS runtime devel)

set(CPACK_INCLUDE_TOPLEVEL_DIRECTORY 0)
set(CPACK_PACKAGE_CONTACT "info@example.com")

set(CPACK_ARCHIVE_COMPONENT_INSTALL On)

set(CPACK_RPM_COMPONENT_INSTALL On)
set(CPACK_RPM_PACKAGE_AUTOREQ On)
set(CPACK_RPM_PACKAGE_AUTOREQPROV Off)
set(CPACK_RPM_DEVEL_PACKAGE_REQUIRES "blas, lapack, atlas, jsoncpp-devel")
set(CPACK_RPM_SAMPLE_PACKAGE_REQUIRES "ffmpeg-devel, jsoncpp-devel")

set(CPACK_DEB_COMPONENT_INSTALL On)
set(CPACK_DEBIAN_DEVEL_PACKAGE_DEPENDS "libopenblas-base, libblas3, libjsoncpp-dev, libjsoncpp1, libopenblas-dev")
set(CPACK_DEBIAN_SAMPLE_PACKAGE_DEPENDS "libavformat-dev, libavcodec-dev, libswscale-dev, libswresample-dev, libavutil-dev, libopenblas-dev")

include(CPack)

Подключив требуемые модули расширяющие CPack, необходимо выставить значения задокументированных переменных для каждого конкретного формата установщика или пакета. Некоторые значения берутся из переменных и параметров CMake, некоторые могут быть заполнены автоматически при выполнение упаковки. После выставления переменных следует подключить собственно модуль CPack через include(CPack).

Как написать конфигурацию для своего проекта?

По созданию своего файла конфигурации есть статья здесь.

В общих чертах, файл конфигурации описывает цели, которые пользователь может использовать в своем проекте. Список целей генерируется CMake при создании экспортируемой сущности, привязанной к целям. Версионирование и проверки целостности конфигурации общего назначения реализованы в модуле CMakePackageConfigHelpers.

include(GNUInstallDirs)
include(CMakePackageConfigHelpers)
configure_package_config_file(res/neuon-config.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/neuon-config.cmake INSTALL_DESTINATION ${CMAKE_INSTALL_DATAROOTDIR})
write_basic_package_version_file( ${CMAKE_CURRENT_BINARY_DIR}/neuon-config-version.cmake VERSION ${version} COMPATIBILITY SameMajorVersion)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/neuon-config.cmake ${CMAKE_CURRENT_BINARY_DIR}/neuon-config-version.cmake DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/neuon/cmake COMPONENT devel)

Шаблон конфигурации может быть похож на:

cmake_policy(PUSH)
cmake_policy(VERSION 3.10)

@PACKAGE_INIT@

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/modules/")

include(CMakeFindDependencyMacro)
find_dependency(Tensorflow)

include ( "${CMAKE_CURRENT_LIST_DIR}/neuon-headers-targets.cmake" )
include ( "${CMAKE_CURRENT_LIST_DIR}/neuon-targets.cmake" )

check_required_components(headers)
check_required_components(neuon)

list(REMOVE_AT CMAKE_MODULE_PATH -1)

cmake_policy(POP)

Как использовать конфигурации других проектов?

Корректно подготовленная конфигурация не требует никаких дополнительных действия для использования.

find_package(Neuon REQUIRED COMPONENTS headers neuon)
target_link_libraries(neuon-sample PRIVATE neuon::neuon)

Конфигурация декларирует какие библиотеки доступны для использования, какие дополнительные зависимости необходимо слинковать с конечным результатом, какие флаги компилятора должны быть выставлены при использовании. Где находятся заголовочные файлы, и библиотеки импорта тоже указывается посредством файла конфигурации и избавляет пользователя от ручного труда.

Как использовать стандартные CMake модули?

Несмотря на регламентированное именование модулей использование их в своих проектах двоякое. Многие стандартные модули CMake подключаются через функцию include(), однако многие модули, выполняющие поиск библиотек, не поддерживающих CMake самостоятельно через конфигурацию полагаются на find_package() в режиме модулей.

include(GNUInstallDirs)
include(CMakePackageConfigHelpers)
include(CPackComponents)
include(CPack)
include(GoogleTest)

find_package(CURL)
find_package(Boost 1.70 MODULE REQUIRED COMPONENTS program_options log)

Библиотека Boost начиная с версии 1.70 обеспечивает поддержку CMake через конфигурации. СMake модуль обладает обратной совместимостью и умеет разрешать местонахождение Boost любой версии, используя конфигурации при наличии и создавая цели-псевдонимы в противном случае.

Как использовать модули из посторонних или личных источников?

Нередки случаи, когда стандартного модуля нет в наличии, или его состояние не удовлетворяет нуждам проекта. В таком случае проект может предоставить свои собственные CMake модули, для использования в своих конфигурациях. Ключевым моментом для использования собственных модулей является параметр CMAKE_MODULE_PATH, перечисляющий пути поиска модулей. Проект или конфигурация проекта могут самостоятельно изменять переменную, выведенную из этого параметра. Например, можно добавить в свой проект модуль, выполняющий заворачивание всех нееобходимых флагов компиляции для использования FFMpeg в цели CMake и связывать свое приложение с этими целями, не беспокоясь о флагах линковки, флагах компилятора и всех зависимостях.

set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH};${CMAKE_CURRENT_SOURCE_DIR}/cmake;${CMAKE_CURRENT_SOURCE_DIR}/depends/sdk/cmake")

project(neuon-sample VERSION ${version})

find_package(Threads REQUIRED)
find_package(spdlog REQUIRED)
find_package(Boost 1.70 REQUIRED COMPONENTS program_options)
find_package(FFMPEG REQUIRED COMPONENTS avcodec avformat swscale swresample)

add_executable(neuon-sample src/neuon_sample.cpp)
target_link_libraries(neuon-sample PRIVATE spdlog::spdlog Threads::Threads Boost::program_options FFMPEG::avcodec FFMPEG::avformat FFMPEG::swscale

При изменении CMAKE_MODULE_PATH в своих конфигурациях, чтобы избежать конфликтов модулей с проектом пользователя, можно использовать функции по работе со списками. После добавления своих путей в переменную и использования, можно удалить эти вхождения из списка.

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/modules/")

include(CMakeFindDependencyMacro)
find_dependency(Tensorflow)

list(REMOVE_AT CMAKE_MODULE_PATH -1)

Как подключать и переиспользовать другие куски CMake скриптов?

CMake позволяет включать части скриптов друг в друга как есть, не выполняя дополнительной работы. Это может быть полезно для переиспользования функционала, когда использование модуля не обосновано, а дублирования хочется избежать. include() включит содержимое указанной файла в использующий файл. Включаемые файлы должны быть реентерабельны, и не изменять глобальное состояние.

include(depends/sdk/cmake/version.cmake)
configure_version(neuon)
configure_birthday(neuon)

Заключение

CMake 3.10+ однозначно полагается на объектную модель использования. Все есть цель. У цели есть свойства. Проект не должен изменять глобальное состояние. Проект описывает свои цели, и использует свойства целей для модификации своего поведения. Модули — расширяют функционал CMake. Конфигурации обеспечивают интерфейс интеграции проектов и зависимостей. Переиспользование функционала доступно и рекомендуется.

Глобальные свойства, параметры и переменные управляются CMake. Проект не должен их менять по своем усмотрению. Проект должен подстраиваться под глобальное состояние.

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

CMake предлагает очень широкий выбор доступных параметров и переменных, не стоит дублировать их в своем проекте.

Использование относительных путей предпочтительнее абсолютных.

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

CMake распространяется как самодостаточный архив под все популярные платформы. Файл конфигурации ограничен версией CMake потребителя, но для сборки и упаковки проекта можно притащить последнюю версию, развернуть локально как часть окружения сборки и пользоваться наиболее свежим функционалом, которые сделан, чтобы делать жизнь авторов проектов проще.

Полезные ссылки

Официальная документация CMake

Поддерживаемая сообществом при участии авторов CMake вики

Официальная страница распространения CMAKE

В чем разница между разными способами включения подпроектов?

CMake предлагает разные способы подключения проектов друг в друга. Если допустить, что проект описывается как минимум одним CMakeLists.txt, то проекты между собой могут быть связаны через add_subdirectory(), include(), ExternalProject_Add().

Основная идея в том, что CMakeLists.txt описывает проект как нечто именованное и версионированное. Директива project() устанавливает некоторые переменные, используемые CMake при генерации и сборке. Как минимум версию проекта.

include() включает содержимое как есть, а в одном CMakeLists.txt не может оказаться две активные директивы project().

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

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

При этом, можно встретить примеры добавлять CMakeLists.txt на каждый уровень вложенности папок — корневая папка, подпапка с файлами исходного кода, в подпапки еще глубже — и каждый из них включать друг в друга. На практике, никакой пользы от этого подхода не наблюдается. Логическое выделение подпроектов с собственным CMakeLists.txt, и корневой CMakeLists.txt включающий подпроекты и при этом выполняющий общепроектные операции по упаковке приводят к элегантно разграниченным проектам в многопроектных системах сборки как Visual Studio. Иметь одно MSVS решение(solution, ugh….) c проектами(projects) по сборке заголовочных файлов, библиотеки и демо-приложения гораздо приятнее, чем иметь с десяток искусственных проектов без четко обозначенного назначения.

In the previous part of the series, we looked at how to add tests to a project. The next step is providing support for deploying, or installing, the built binaries to our users. No matter if you’re working on a library or an executable application, users need to be able to deploy the binaries to a location of their choosing in a reliable way. In this part of the series, we take a closer look at installing libraries.

Defining installation requirements

What does it mean to “install” a library? Let’s first consider how a library is used. A library will generally be a dependency of another project – either a larger library or an application. It could be a development (build) dependency, or it could be runtime dependency. In the former case, the library could be either static or shared. In the latter case, it will always be a shared library.

A practical definition for “installing a library” could then be something along the lines of

“Deployment of the binaries, be it static or shared, and possibly header files – for development purposes, to a directory of user’s choosing, in a way that exposes the binaries, headers and potential information about transitive dependencies, for convenient consumption by depending projects.”

This may be somewhat vague, but the key point, I believe, is the convenience. In the context of CMake this would mean supporting the standard ways of incorporating dependencies into a project. In part 6 I introduced the FetchContent module. It’s a great solution for including dependencies that need to be built alongside the project. However, it’s not quite sufficient for binaries – it could be used to download the package, but what then? We still need the information about include and link paths, possibly defines, flags and transitive dependencies. In CMake all this is handled by Find modules, or the more recent Config files. Both of these are a standard way of exposing targets that encapsulate all the necessary information to the user. Find modules and Config files can be consumed with the help of the find_package command – it will find the Find module or Config file associated with the given package and process them, thus making targets they define available. But first things first. Let’s forget about Config files and find_package for a moment and see how to add the most basic installation support.

One more thing before I get into it. I first need to mention that deploying libraries, especially if multiplatform support is it be considered, is a huge topic that could be approached in many different ways. The number of variables to consider is simply too large, especially for an introductory post. Instead of discussing all the possibilities I will present and describe an approach that supports a decent number of use cases on Linux as well as on Windows. I have no idea about Apple platforms, sorry not sorry. Unfortunately for the same reasons I also do not consider how to handle shared libraries. I wouldn’t be able to cover this topic well here, so I’d rather postpone it to a future, dedicated post.

The approach I’m about to describe provides support for relocateable installs, that are find_package‘able via generated Config files. It’s a basic, but more or less standard setup that could be extended to accomodate specific project’s needs.

Install directory layout

One of the first things to consider when preparing for project installation is the install directory layout. Where the static and shared libraries, executables, and headers go. This is the bare minimum, one might also want to consider any possibly generated documentation, scripts, etc. Unless a project has some specific requirements regarding this layout, there is a standard approach that can be used. Anyone vaguely familiar with Linux would expect the following:

.
├── bin/        # executable binaries
├── include/    # header files
└── lib/        # static or shared libraries

And this is exactly the layout I’m going for. The specified paths are relative to a root install directory, which makes the installation relocateable – the user isn’t forced to install the package to /usr/, /usr/local, /opt/, or any other path one might think to hardcode. Instead only the relative layout below the root install directory is preserved – this is sufficient to relyably use the package.

This standard layout is provided by the GNUInstallDirs module. Despite the name, the module handles the layout in a cross-platform way, e.g. on Windows the DLLs will go into bin/ rather than lib/, as expected. Once included this module exposes the following variables (plus a few more):

CMAKE_INSTALL_BINDIR        # bin/
CMAKE_INSTALL_LIBDIR        # lib/
CMAKE_INSTALL_INCLUDEDIR    # include/

These variables can be used when specifying install paths, instead of hardcoding them. This handles the considerations of the target platform for us.

Installing targets

Now that we know what we’d like the install directory layout to look like we can proceed to actually installing the targets defined in our project and the resulting binaries. This is actually relatively simple and is handled by the aptly named install command. All that’s required is addition of the following lines to the top-level CMakeLists.txt:

include(GNUInstallDirs)

# (...)

install(TARGETS Add Subtract Maths MathsDemo
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

Seems too easy, right? Because that’s not the whole story of course. First, since in part 4 of the series I introduced the concept of modularization and insisted on applying it across the project it would now also make sense to handle installation on a per-module basis – each module should be responsible for correctly installing itself. So instead of calling install once on all targets it might be better to call it separately for each module. It’s a little more work, but it leads to more maintainable project setup. Specifying the DESTINATION for each artifact type seems like some boilerplate that could be done away with by wrapping the call in a function. That might be a reasonable thing to do, but since CMake 3.14 it’s unnecessary – the values given above are the default, if the GNUInstallDirs module is included. Let’s rely on that, and install each module separately:

CMakeLists.txt:

include(GNUInstallDirs)

# (...)

install(TARGETS MathsDemo)

add/CMakeLists.txt:

install(TARGETS Add)

subtract/CMakeLists.txt:

install(TARGETS Subtract)

Maths/CMakeLists.txt:

install(TARGETS Maths)

As a whole this is exquivalent to the previous single install command call. This approach however, makes each module self-contained. Anyway, let’s configure, build and install the project, to see what happens. The first thing to do when testing project installation is to set the CMAKE_INSTALL_PREFIX variable to a local install directory. Either specify it on the command line or hardcode it temporarily in the CMakeLists.txt. I’ve chosen the first approach:

$ cmake -DCMAKE_INSTALL_PREFIX:PATH=./install -S . -B build
$ cmake --build build -j7
$ cmake --build build --target install

-- Install configuration: "Debug"
-- Installing: /home/user/cmake_fundamentals/install/include
-- Installing: /home/user/cmake_fundamentals/install/include/gmock
-- Installing: /home/user/cmake_fundamentals/install/include/gmock/gmock-cardinalities.h
-- Installing: /home/user/cmake_fundamentals/install/include/gmock/gmock-generated-function-mockers.h.pump
(...)
-- Installing: /home/user/cmake_fundamentals/install/lib/libAdd.a
-- Installing: /home/user/cmake_fundamentals/install/lib/libSubtract.a
-- Installing: /home/user/cmake_fundamentals/install/lib/libMaths.a
-- Installing: /home/user/cmake_fundamentals/install/bin/MathsDemo

Wait, what? Why are gmock and gtest being installed? Since we’ve chosen to use FetchContent to embed googletest within our project, and gtest calls install for its own targets, it is being installed alongside our project. This can be easily dealt with by setting INSTALL_GTEST to OFF just before FetchContent_MakeAvailable(googletest). The relevant lines in tests/CMakeLists.txt now look as follows:

set(INSTALL_GTEST OFF)
FetchContent_MakeAvailable(googletest)

That was easy only because the googletest guys were nice enough to think about supporting this use case and made the installation conditional. The same should be done for our project if we wanted to support the use case of embeding our project via FetchContent as well. Let’s not get too ahead of ourselves though. Back to basic target installation.

If the project is intalled now, we get the following output:

$ cmake --build build --target install
Install the project...
-- Install configuration: "Debug"
-- Installing: /home/user/cmake_fundamentals/install/lib/libAdd.a
-- Installing: /home/user/cmake_fundamentals/install/lib/libSubtract.a
-- Installing: /home/user/cmake_fundamentals/install/lib/libMaths.a
-- Installing: /home/user/cmake_fundamentals/install/bin/MathsDemo

As you can see the libraries are now installed into the expected directories. You may have noticed that the header files are not installed though. This is because headers need to be handled explictly, to accomodate the potential layout differences – it’s unlikely that one would want all headers of a library to be dumped directly into the include directory. It’s much more likely to have some layout that logically groups the header files. We’ll deal with that next. Oh, by the way. I have chosen to rename the Main target to an equaly unimaginative MathsDemo.

Since the project is already modularized this will be straightfoward. Each module will of course be responsible for installing its headers. The layout should correspond to the module layout in the source tree. To achieve this we’ll need to use a different form of the install command – install(DIRECTORY …) as one might expect it install an entire directory. We might also choose to install on a per-file basis, but let’s go with the DIRECTORY approach, since it’s more succinct.

add/CMakeLists.txt:

install(DIRECTORY add
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

subtract/CMakeLists.txt:

install(DIRECTORY subtract
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

maths/CMakeLists.txt:

install(DIRECTORY maths
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

Again, nothing too difficult to understand. This could be wrapped along with the previous install call into a single function or macro to make the whole process even more painless. Re-installing the project now results in the following output:

-- Installing: /home/user/cmake_fundamentals/install/lib/libAdd.a
-- Installing: /home/user/cmake_fundamentals/install/include/add
-- Installing: /home/user/cmake_fundamentals/install/include/add/calc_status.h
-- Installing: /home/user/cmake_fundamentals/install/include/add/add.h
-- Installing: /home/user/cmake_fundamentals/install/lib/libSubtract.a
-- Installing: /home/user/cmake_fundamentals/install/include/subtract
-- Installing: /home/user/cmake_fundamentals/install/include/subtract/subtract.h
-- Installing: /home/user/cmake_fundamentals/install/lib/libMaths.a
-- Installing: /home/user/cmake_fundamentals/install/include/maths
-- Installing: /home/user/cmake_fundamentals/install/include/maths/maths.h
-- Installing: /home/user/cmake_fundamentals/install/bin/MathsDemo

Right, we now have the install layout we have defined in the first paragraph. So far so good. The next step is to make this installation consumable by other projects, that is, exposing all the necessary information – include directories, paths to the actual libraries, etc. in the form of targets. This is done using export targets.

Export target installation

Every install(TARGETS …) command may optionally specify an EXPORT set to which the target belongs to, thus adding the target to that EXPORT set. An EXPORT set (target) carries full information about properties of each target included into the EXPORT, and all the inter-target dependencies. We will have a single EXPORT set for the entire project (library), let’s name it Maths, since that’s the library we’d like to expose to the end user. Each install(TARGETS …) call needs to be extended as follows:

CMakeLists.txt:

include(GNUInstallDirs)

# (...)

install(TARGETS MathsDemo
    EXPORT Maths
)

add/CMakeLists.txt:

install(TARGETS Add
    EXPORT Maths
)

subtract/CMakeLists.txt:

install(TARGETS Subtract
    EXPORT Maths
)

Maths/CMakeLists.txt:

install(TARGETS Maths
    EXPORT Maths
)

Doing so loads the Maths export target with all the necessary information, it doesn’t expose it to the user however. That’s done by installing the export target itself, like so:

install(EXPORT Maths
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Maths
    NAMESPACE Maths::
)

Let’s unpack what’s going on here. We’re saying that the EXPORT target Maths should be installed to a directory lib/cmake/Maths – this is a CMake convention – I explain the why later. The NAMESPACE argument means that all targets exposed by the installed EXPORT target will have the given prefix – here Maths::. This means that the end user of our library will need to include the Add library by linking Maths::Add, rather than just Add. The namespace is introduced in order to avoid name clashes with other packages. Things are starting to get a little complicated. Fret not, we’re nearing the end. Though trying to install the project now would result in a number of error messages:

CMake Error in add/CMakeLists.txt:
  Target "Add" INTERFACE_INCLUDE_DIRECTORIES property contains path:

    "/home/user/cmake_fundamentals/add"

  which is prefixed in the source directory.


CMake Error: install(EXPORT "Maths" ...) includes target "Add" which requires target "ProjectConfiguration" that is not in any export set.

(...)

It all boils down to two issues:

1. The targets in the export set contain include directories pointing to an absolute path in the source tree – there is zero chance that these paths will be correct on the end-users machine. We need a way to swap these paths out for correct paths, relative to the install directory.
2. The EXPORT target needs to be able to provide full inter-target dependency context, but the ProjectConfiguration target is not installed. We need to install it, even though it’s only an interface target, and doing so will have no effect other than adding information about its dependencies to other targets.

The second issue is simpler, so let’s fix it first. It’s enough to add ProjectConfiguration to the install(TARGETS …) call in the top-level CMakeLists.txt:

CMakeLists.txt:

include(GNUInstallDirs)

# (...)

install(TARGETS MathsDemo ProjectConfiguration
    EXPORT Maths
)

The first issue requires more explenation. Each target defined in the project also adds include directories to its INCLUDE_DIRECTORIES and INTERFACE_INCLUDE_DIRECTORIES properties. For example, the Add target:

target_include_directories(Add
    PUBLIC
        ${CMAKE_CURRENT_SOURCE_DIR}
)

The above call appends an absolute path expansion of CMAKE_CURRENT_SOURCE_DIR to both properties. This path is absolute and valid only when building the project. Since we want installed packages to be relocateable this path needs to be replaced with a path relative to the install root directory upon installation. This is done using a set of boilerplate generator expressions, the above target_include_directories command needs to be replaced with the following:

target_include_directories(Add
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
)

Without going into too much detail about how generator expressions work (see my post about generator expressions if you’d like to know more) this call will do exactly what we want – it will expand to the path in the source tree when building the project and to a path relative to CMAKE_INSTALL_INCLUDEDIR when the target is installed. After applying the same modification to all targets, the project can finally be installed.

$ cmake --build build -t install
(...)
-- Installing: /home/user/cmake_fundamentals/install/lib/cmake/Maths/Maths.cmake
-- Installing: /home/user/cmake_fundamentals/install/lib/cmake/Maths/Maths-debug.cmake

Two new files are installed with this call – Maths.cmake and Maths-debug.cmake. These are generated by installing the EXPORT target and contain all the information necessary to consume our library. Inspecting them is an excercise for the interested reader ( 😉 ). These files are the basis for adding the find_package support. The rest will be handled by yet another CMake module – CMakePackageConfigHelpers.

Package Config

The CMakePackageConfigHelpers module exposes a set of functions for generating package Config file – one of the ways to support the find_package command. The other is writing a Find module – this is the old way of doing things and should generally be avoided for new projects. Generating the Config file is relatively straightforward. It involves three steps:

1. Write a <project-name>Config.cmake.in template file, which will be used to generate the Config.
2. Call the configure_package_config_file function to actually generate the Config file.
3. Install the generated Config file, the same way you would any other file.

The template file needs to be provided, because the decision of what it needs to contain is up to the us. In the most basic cases however, the same, very simple configuration file can be used:

cmake/MathsConfig.cmake.in:

@PACKAGE_INIT@

include(${CMAKE_CURRENT_LIST_DIR}/Maths.cmake)
set_and_check(Maths_INCLUDE_DIR "@PACKAGE_CMAKE_INSTALL_INCLUDEDIR@")
set(Maths_LIBRARIES Maths::Maths)
check_required_components(Maths)

This correctly supports relocateable packages on all platforms. Notice that the Maths.cmake generated by installing the EXPORT target is being included here – that’s where all of the real work is done. Next, variables exposing the include path and the libraries are set. This is not strictly required, but can be expected by some users. Notice that a new set_and_check command is used here. This is a function provided by the

CMakePackageConfigHelpers

module, all it does is sets the variable and ensures the pats are valid. The

check_required_components

function should be self explenatory. All that’s left to do is configuring and installing the file:

include(CMakePackageConfigHelpers)

configure_package_config_file(
    cmake/MathsConfig.cmake.in                      # the template file
    ${CMAKE_CURRENT_BINARY_DIR}/MathsConfig.cmake   # destination
    PATH_VARS CMAKE_INSTALL_INCLUDEDIR
    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Maths
)

install(FILES
    ${CMAKE_CURRENT_BINARY_DIR}/MathsConfig.cmake
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Maths
)

What happens here is the Config template is used to generate the MathsConfig.cmake file, we also need to provide the information about where this Config file will be installed, so that the @PACKAGE_INFO@ tag is expanded correctly. We then actually install the generated Config into the same directory into which the Maths.cmake and Maths-debug.cmake were installed. Also note the PATH_VARS argument – variables passed in here, need to be prefixed with PACKAGE_ in the template. This ensures that the path is correctly expanded to a path prefixed in the package installation directory.

Place all of the above commands at the bottom of the top-level CMakeLists.txt for now. Aside for the template file – it should be located in the cmake directory. Let’s run the install target and inspect the result.

$ cmake --build build --target install
Install the project...
(...)
-- Installing: /home/user/cmake_fundamentals/install/lib/cmake/Maths/MathsConfig.cmake

As you can see the MathsConfig.cmake file has been installed alongside the library. And that’s it really. The package installation is now well behaved, relocateable and supports the find_package command. Before I prove to you that all this works, there’s a few more improvements that we could apply.

Supporting multiple configurations

If you look closely at the installed scripts, one of them is named Maths-debug.cmake – it’s configuration-specific. This implies that there might also need to exist Maths-release.cmake, and possibly other. The current setup could be considered fine if we required that each configuration is installed into a different install-prefix directory. This requirement is limiting. A common convention is to ensure that both debug and release build of the library can coexist by adding a suffix to the debug configuration. This is done by specifying an appropriate property on the target:

set_target_properties(Add
    PROPERTIES
        DEBUG_POSTFIX _d
)

This will cause _d to be appended to the binary resulting from debug builds of the Add target. Of course the same needs to be done for all targets in the project.

If you install the project now you’ll see that all the libraries have the newly specified suffix.

$ cmake --build build --target install
Install the project...
-- Install configuration: "Debug"
-- Installing: /home/user/cmake_fundamentals/install/lib/libAdd_d.a
-- Installing: /home/user/cmake_fundamentals/install/lib/libSubtract_d.a
-- Installing: /home/user/cmake_fundamentals/install/lib/libMaths_d.a
(...)

Some further considerations would be to add versioning and support for shared libraries – as is, if the project was built as a shared library it could be installed just fine, maybe even linked to, but you wouldn’t have much luck running the final binary. But like I already mentioned at the start I’d rather cover this topic in a dedicated post. For now, let’s briefly address how to add versioning to packages.

Versioning

Setting a project version number is rather simple – all it takes to do is is to pass an additional argument to the very first project command call:

project(Fundamentals VERSION 0.1.0)

This will have the result of the following cache variables being defined:

For completeness sake, I’ll just mention that a PROJECT_VERSION_TWEAK variable is defined as well, but this isn’t compliant with semver, so I’m choosing to ignore it (it’s debatable if semver makes sense in the context of C++, but that’s a different post). In addition to the above, there’s also a project-call-specific variable defined, corresponding to each of the above. This follows the pattern of <project-name>_VERSION, etc. This might be relevant in a larger project where you might want to package and version certain components of the project separately.

So the project has a version, great. How do we actually propagate that to the installed package? CMakePackageConfigHelpers has you covered. In addition to the configure_package_config_file function it also exposes write_basic_package_version_file, which does exactly that. It generates a version file, which then also needs to be installed, same as the Config file. An exaple follows.

write_basic_package_version_file(
  ${CMAKE_CURRENT_BINARY_DIR}/MathsConfigVersion.cmake
  VERSION ${PROJECT_VERSION}
  COMPATIBILITY SameMajorVersion
)

install(FILES
    # ...
    ${CMAKE_CURRENT_BINARY_DIR}/MathsConfigVersion.cmake
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Maths
)

Note the specified COMPATIBILITY – this let’s find_package determine if the package found is compatible with the one requested by the consuming project. SameMajorVersion is compatible with the semver concept. The following alternatives are available: AnyNewerVersion, SameMinorVersion, ExactVersion. You must decide for yourself which one suits your project at its current stage the best, taking into account API and ABI stability.

Installing the project now will result in the MathsConfigVersion.cmake file being installed, as expected:

Install the project...
(...)
-- Installing: /home/user/cmake_fundamentals/install/lib/cmake/Maths/MathsConfigVersion.cmake

And that’s it. Shared library support aside, this is a complete basic library packaging setup. The only thing to do is testing if it all works as expected.

Finding packages

The most direct way to test this solution would be to define a minimal project which uses it. Instead of defining something completely new I’ll just move the code associated to the MathsDemo executable to a separate project. I’ll spare you the details of what needs to be removed from the Fundamentals project, but here’s the complete setup of the test project:

directory tree:
.
├── CMakeLists.txt
└── main.cpp

CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(HelloInstalling)

find_package(Maths 0.1.0)

add_executable(MathsDemo)
target_sources(MathsDemo
    main.cpp
)

target_link_libraries(MathsDemo
    PRIVATE
        Maths::Maths
)

main.cpp (Same as before, moved from the Fundamentals project):
#include <iostream>
#include <limits>

#include <maths/maths.h>

void use_add(int a, int b)
{
    Maths::calc_status cs{};
    auto const result = Maths::add(a, b, cs);
    if (cs == Maths::calc_status::success)
    {
        std::cout << a << " + " << b << " = " << result << "\n";
    }
    else
    {
        std::cout << "Error calculating " << a << " + " << b << "\n";
    }
}

int main()
{
    const int a{42};
    const int b{102};

    use_add(a, b);
    use_add(a, std::numeric_limits<int>::max());
}

The interesting parts are in the CMakeLists.txt in bold. The find_package command call searches for the Maths package of the specified version (enforcing the compatibility specified in the package). Once the package is found, all of the targets defined in the MathsConfig.cmake file are available. In this case we’re linking the Maths::Maths target to the MathsDemo executable.

How does CMake know where to search for the package? By default it searches some platform-specific default directories, on a Unix-y system this is something like:

/usr/lib/cmake/<name>
/usr/lib/share/cmake/<name>
/usr/lib/<name>/cmake
(...)

This is just an example, see the documentation for the full story. What does this mean in practice? System-wide installed packages will be found without any additional actions needing to be done. What if we don’t want to install a package system-wide just for testing? Before the system paths are searched, find_package first searches all paths listed in the CMAKE_PREFIX_PATH variable. This is the best way of ensuring that a package is found without hard-coding any paths.

Let’s see an exapmle. In my case the cmake_fundamentals and the test_project are sybling directories:

.
├── cmake_fundamentals
│   └── install
└── test_project

The CMAKE_PREFIX_PATH needs to be set to the relative or absolute path of the cmake_fundamentals/install directory.

$ cmake -DCMAKE_PREFIX_PATH:PATH=cmake_fundamentals/install -B test_project/build -S test_project
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/test_project/build

$ cmake --build test_project/build/
Scanning dependencies of target MathsDemo
[ 50%] Building CXX object CMakeFiles/MathsDemo.dir/main.cpp.o
[100%] Linking CXX executable MathsDemo
[100%] Built target MathsDemo

$ test_project/build/MathsDemo
42 + 102 = 144
Error calculating 42 + 2147483647

Summary

In this post I demonstrated how to set up simple packaging for a library. This is a basic but solid skeleton, suitable for extension to accomodate project needs. A first good step would be to encapsulate all of the installation logic scattered across the project into a module. In the next post I’ll follow up on the packaging and demonstrate how to set up projects to support the FetchContent use case – thus making it possible to embed a dependency the same way we did googletest.

One more thing. No more posts this long. I promise.

References

• Git gist
• GNUInstallDirs
• CMakePackageConfigHelpers
• find_package
• FetchContent