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

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

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

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

Введение

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