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

• Введение

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

Введение

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