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

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

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

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

Введение

Для разработчиков, желающих использовать 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/ в приведенном выше примере.

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

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

Часто документация стороннего пакета указывает имена доступных импортированных целей после успешного 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 см. в cmake-buildsystem(7).

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

Сторонние библиотеки, не предоставляющие пакеты файлов конфигурации, все же могут быть найдены с помощью команды 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_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.