Руководство по использованию зависимостей

• Введение
• Библиотеки, предоставляющие пакеты файлов конфигурации

• Импортированные целевые компоненты из пакетов

  • Библиотеки, не предоставляющие пакеты файлов конфигурации

Введение

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

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

Если требуемая зависимость не найдена командой cmake(1), в кэш записывается запись, содержащая NOTFOUND значение. Это значение можно заменить, указав его в командной строке или в инструменте ccmake(1) или cmake-gui(1). См. руководство User Interaction Guide для получения дополнительной информации о настройке записей кэша.

Библиотеки, предоставляющие пакеты файлов конфигурации

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

Файлы конфигурации обычно находятся в каталоге, имя которого соответствует шаблону lib/cmake/<PackageName>, хотя они могут быть и в других местах. <PackageName> соответствует использованию в коде CMake с командой find_package(), например find_package(PackageName REQUIRED).

Каталог lib/cmake/<PackageName> будет содержать файл, который называется либо <PackageName>Config.cmake, либо <PackageName>-config.cmake. Это точка входа в пакет для CMake. В каталоге также может присутствовать отдельный необязательный файл с именем <PackageName>ConfigVersion.cmake. Этот файл используется CMake для определения того, удовлетворяет ли версия пакета сторонних разработчиков требованиям, заданным в команде find_package(), которая задает ограничения на версии. Можно не указывать версию при использовании команды find_package(), даже если файл ConfigVersion присутствует.

Если файл Config.cmake найден и указанная (необязательно) версия удовлетворяет требованиям, команда CMake find_package() считает пакет найденным, и предполагается, что весь пакет библиотеки завершён как задумывалось.

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

Для использования пакета бинарных файлов сторонних разработчиков с помощью CMake необходимо, чтобы команды find_package() успешно нашли пакет. Если расположение пакета известно CMake, то вызов find_package() должен пройти успешно. Каталоги, известные CMake, зависят от платформы. Например, пакеты, установленные на Linux с помощью стандартного менеджера пакетов, будут найдены в префиксе /usr автоматически. Аналогично, пакеты, установленные в Program Files на Windows, будут найдены автоматически.

Пакеты, которые не найдены автоматически, находятся в местах, непредсказуемых для CMake, таких как /opt/mylib или $HOME/dev/prefix. Это нормальная ситуация, и CMake предоставляет несколько способов для пользователей указать, где найти такие библиотеки.

Переменная CMAKE_PREFIX_PATH может быть установлена при вызове CMake. Она рассматривается как список путей для поиска пакетов файлов конфигурации. Пакет, установленный в /opt/somepackage, обычно устанавливает файлы конфигурации, такие как /opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake. В этом случае, /opt/somepackage необходимо добавить в CMAKE_PREFIX_PATH.

Переменная среды CMAKE_PREFIX_PATH также может быть заполнена префиксами для поиска пакетов. Подобно переменной среды PATH, это список, и необходимо использовать разделитель элементов списка переменной среды, специфичный для платформы (: на Unix и ; на Windows).

Переменная CMAKE_PREFIX_PATH обеспечивает удобство в случаях, когда необходимо указать несколько префиксов или когда несколько разных бинарных пакетов доступны в одном префиксе. Пути к пакетам также можно указать, задав переменные, соответствующие <PackageName>_DIR, например SomePackage_DIR. Обратите внимание, что это не префикс, а полный путь к каталогу, содержащему файл пакета в стиле конфигурации, например /opt/somepackage/lib/cmake/SomePackage/ в приведенном выше примере.

Импортированные целевые компоненты из пакетов

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

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

Полный пример простого использования сторонней библиотеки может выглядеть так:

cmake_minimum_required(VERSION 3.10)
project(MyExeProject VERSION 1.0.0)

find_package(SomePackage REQUIRED)
add_executable(MyExe main.cpp)
target_link_libraries(MyExe PRIVATE SomePrefix::LibName)

См. cmake-buildsystem(7) для получения дополнительной информации о разработке системы сборки CMake.

Библиотеки, не предоставляющие пакеты файлов конфигурации

Библиотеки сторонних разработчиков, не предоставляющие пакеты файлов конфигурации, все ещё могут быть найдены с помощью команды find_package(), если доступен файл FindSomePackage.cmake.

Эти пакеты модулей отличаются от пакетов файлов конфигурации следующим:

1. Их не должен предоставлять сторонний разработчик, разве что в виде документации.
2. Наличие файла Find<PackageName>.cmake не указывает на наличие самих бинарных файлов.
3. CMake не ищет файлы Find<PackageName>.cmake в CMAKE_PREFIX_PATH. Вместо этого CMake ищет такие файлы в переменной CMAKE_MODULE_PATH. Пользователи часто устанавливают CMAKE_MODULE_PATH при запуске CMake, и проекты CMake часто добавляют значения в CMAKE_MODULE_PATH для использования локальных пакетов файлов модулей.
4. CMake поставляет файлы Find<PackageName>.cmake для некоторых third party packages для удобства в случаях, когда сторонний разработчик не предоставляет пакеты файлов конфигурации напрямую. Эти файлы создают нагрузку на поддержку CMake, поэтому новые модули Find обычно больше не добавляются в CMake. Сторонние разработчики должны предоставлять пакеты файлов конфигурации вместо того, чтобы полагаться на модули Find, предоставляемые CMake.

Пакеты файлов модулей также могут предоставлять импортированные целевые компоненты. Полный пример поиска такого пакета может выглядеть так:

cmake_minimum_required(VERSION 3.10)
project(MyExeProject VERSION 1.0.0)

find_package(PNG REQUIRED)

# Add path to a FindSomePackage.cmake file
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
find_package(SomePackage REQUIRED)

add_executable(MyExe main.cpp)
target_link_libraries(MyExe PRIVATE
    PNG::PNG
    SomePrefix::LibName
)

Переменная <PackageName>_ROOT также используется как префикс для вызовов find_package() при использовании модульно-файловых пакетов, таких как FindSomePackage.