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

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

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

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

Введение

Для разработчиков, желающих использовать 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().

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