cmake_pkg_config

• Краткое описание
• Введение
• Цели PkgConfig
• Общие параметры
• Сигнатуры

Обрабатывает файлы пакетов в формате pkg-config.

Краткое описание

cmake_pkg_config(EXTRACT <package> [<version>] [...])
cmake_pkg_config(POPULATE <package> [<version>] [...])
cmake_pkg_config(IMPORT <package> [<version>] [...])

Введение

Эта команда нативно генерирует переменные и цели CMake из файлов пакетов в формате pkg-config, не вызывая реализацию pkg-config и даже не требуя её наличия. <package> — это либо абсолютный путь к файлу пакета, либо имя пакета, по которому будет выполняться поиск с использованием типичных шаблонов поиска pkg-config. Необязательная строка <version> имеет тот же формат и семантику, что и спецификатор версии в стиле pkg-config, за исключением того, что, если оператор сравнения не указан, предполагается =.

Цели PkgConfig

cmake_pkg_config может рекурсивно создавать имена, подобные целям, в глобальной области видимости для разрешения пакета IMPORT или команды POPULATE. Эти имена имеют вид @foreign_pkgcfg::[<prefix>_]<package> и доступны через свойство цели INTERFACE_LINK_LIBRARIES цели, созданной с помощью IMPORT.

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

Цели pkg-config повторно используются между командами. После разрешения имени пакета с помощью POPULATE или IMPORT (но не EXTRACT) все последующие запросы этого имени пакета этими командами будут разрешаться в ранее созданную цель pkg-config.

EXTRACT всегда выполняет полный поиск имени пакета, чтобы обеспечить поиск нескольких установок одного пакета в пользовательских схемах управления зависимостями.

Общие параметры

У этой команды есть несколько сигнатур, некоторые параметры которых являются общими. Это:

EXACT / QUIET / REQUIRED

Параметр EXACT требует точного совпадения строки версии (включая пустую строку, если версия не указана), переопределяя обычный алгоритм сравнения версий pkg-config. При этом игнорируется любой оператор сравнения, указанный в строке версии.

Параметр QUIET отключает информационные сообщения, в том числе сообщения о том, что пакет не найден, если он не REQUIRED. Параметр REQUIRED прекращает обработку с сообщением об ошибке, если пакет не найден.

STRICTNESS <mode>

Задаёт строгость проверки содержимого файлов пакетов при разборе и разрешении зависимостей. Если файл недопустим в соответствии с заданным режимом строгости, команда завершится с ошибкой. Возможны следующие режимы:

• STRICT: В точности соответствует поведению исходной реализации FDO pkg-config. Переменные и ключевые слова должны быть уникальными. Переменные необходимо определять до их использования. Ключевые слова Name, Description и Version должны присутствовать. Общая структура файла должна быть корректной и поддаваться разбору.
• PERMISSIVE: В точности соответствует поведению реализации pkgconf. Повторные определения переменных переопределяют предыдущие. Повторные ключевые слова добавляются. Неопределённые переменные разрешаются в пустые строки. Ключевые слова Name, Description и Version должны присутствовать. Общая структура файла должна быть корректной и поддаваться разбору.
• BEST_EFFORT: Такое же поведение, как у PERMISSIVE в отношении повторных или неинициализированных переменных и ключевых слов, но команда не завершится с ошибкой ни при каких условиях. Файлы пакетов, для которых требуется BEST_EFFORT, не пройдут проверку во всех остальных основных реализациях, поэтому их следует исправить.

По умолчанию используется режим строгости PERMISSIVE.

ENV_MODE

Определяет, какие переменные среды будут опрашиваться при выполнении команды. Возможны следующие режимы:

• FDO: Запрашивает только исходный набор переменных среды PKG_CONFIG_*, используемый реализацией freedesktop.org pkg-config.
• PKGCONF: Запрашивает более широкий набор переменных среды, используемый реализацией pkgconf.

• IGNORE: Полностью игнорирует наличие, отсутствие и значения переменных среды. В случаях, когда переменная среды была бы запрошена, она считается определённой, но имеющей пустое значение для целей выполняемой операции. Текущая среда при этом не изменяется. Для логических переменных среды, таких как PKG_CONFIG_ALLOW_*, это означает, что они считаются истинными.

  PKG_CONFIG_SYSROOT_PATH является небольшим исключением. При использовании ENV_MODE IGNORE по умолчанию не добавляется корневой путь, а для pc_sysrootdir сохраняется значение по умолчанию /.

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

PC_LIBDIR <path>...

Переопределяет расположение по умолчанию для поиска файлов пакетов; также используется для вычисления переменной пакета pc_path.

Если этот параметр не задан, каталог библиотек по умолчанию определяется первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_PC_LIB_DIRS
2. Переменная среды PKG_CONFIG_LIBDIR
3. Результат выполнения pkg-config --variable pc_path pkg-config
4. Значение по умолчанию, зависящее от платформы

PC_PATH <path>...

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

Если этот параметр не задан, пути по умолчанию определяются первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_PC_PATH
2. Переменная среды PKG_CONFIG_PATH
3. Пустой список

DISABLE_UNINSTALLED <bool>

Переопределяет правила поиска файлов пакетов «неустановленных» пакетов. Это файлы пакетов с суффиксом «-uninstalled», описывающие пакеты, напрямую подключённые из дерева сборки.

Обычно такие файлы пакетов имеют более высокий приоритет, чем файлы установленных пакетов. Если DISABLE_UNINSTALLED имеет значение true, поиск «неустановленных» пакетов отключается.

Если этот параметр не задан, правила поиска по умолчанию определяются первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED
2. Если переменная среды PKG_CONFIG_DISABLE_UNINSTALLED определена, поиск отключается; в противном случае он включается.

PC_SYSROOT_DIR <path>

Переопределяет корневой путь, который будет добавляться к путям, указанным во флагах компиляции -I и расположениях поиска библиотек -L; также используется для вычисления переменной пакета pc_sysrootdir.

Если этот параметр не задан, корневой путь по умолчанию определяется первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_SYSROOT_DIR
2. Переменная среды PKG_CONFIG_SYSROOT_DIR
3. Если корневой путь недоступен, к путям каталогов включаемых файлов и библиотек ничего не добавляется, а pc_sysrootdir устанавливается в /

TOP_BUILD_DIR <path>

Переопределяет путь к верхнему каталогу сборки, используемый для вычисления переменной пакета pc_top_builddir.

Если этот параметр не задан, путь к верхнему каталогу сборки по умолчанию определяется первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_TOP_BUILD_DIR
2. Переменная среды PKG_CONFIG_TOP_BUILD_DIR
3. Если путь к верхнему каталогу сборки недоступен, переменная пакета pc_top_builddir не задаётся

PREFIX <name>

Указание префикса создаёт отдельную коллекцию целей pkg-config, не связанную с ранее заполненными целями. Это позволяет одновременно использовать несколько версий одного пакета, например пакеты из разных корневых файловых систем.

По умолчанию используется пустая строка в качестве префикса.

BIND_PC_REQUIRES <<name>=<target>>...

Список пар <name>=<target>, где name — имя пакета, указанное в списке Requires файла pkg-config, а target — имя цели CMake (не цель pkg-config).

Если имя пакета указано в списке Requires пакета, вместо него будет использована связанная с ним цель CMake. Это поведение применяется ко всем зависимостям в графе pkg-config, цели для которых ещё не были созданы.

Сигнатуры

cmake_pkg_config(EXTRACT <package> [<version>] [...])

Добавлено в версии 3.31.

Извлекает содержимое пакета в переменные.

cmake_pkg_config(EXTRACT <package> [<version>]
                [REQUIRED] [EXACT] [QUIET]
                [SYSTEM_INCLUDE_DIRS <path>...]
                [SYSTEM_LIBRARY_DIRS <path>...]
                [ALLOW_SYSTEM_INCLUDES <bool>]
                [ALLOW_SYSTEM_LIBS <bool>]
                [STRICTNESS <mode>]
                [ENV_MODE <mode>]
                [PC_LIBDIR <path>...]
                [PC_PATH <path>...]
                [DISABLE_UNINSTALLED <bool>]
                [PC_SYSROOT_DIR <path>]
                [TOP_BUILD_DIR <path>])

Из содержимого файла пакета будут заполнены следующие переменные:

SYSTEM_INCLUDE_DIRS

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

Если этот параметр не задан, каталоги по умолчанию определяются первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS
2. Переменная среды PKG_CONFIG_SYSTEM_INCLUDE_PATH
3. Результат выполнения pkgconf --variable pc_system_includedirs pkg-config
4. Значение по умолчанию, зависящее от платформы

Кроме того, если ENV_MODE имеет значение PKGCONF, переменная CMAKE_PKG_CONFIG_PKGCONF_INCLUDES будет добавлена в список, если она доступна. Если она недоступна, будут запрошены и добавлены следующие переменные среды:

• CPATH
• C_INCLUDE_PATH
• CPLUS_INCLUDE_PATH
• OBJC_INCLUDE_PATH
• INCLUDE (только для Windows)

SYSTEM_LIBRARY_DIRS

Переопределяет «системные» каталоги, используемые для преобразования флагов каталогов библиотек в CMAKE_PKG_CONFIG_LIBS и производных переменных.

Если этот параметр не задан, каталоги по умолчанию определяются первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_SYS_LIB_DIRS
2. Переменная среды PKG_CONFIG_SYSTEM_LIBRARY_PATH
3. Результат выполнения pkgconf --variable pc_system_libdirs pkg-config
4. Значение по умолчанию, зависящее от платформы

Кроме того, если ENV_MODE имеет значение PKGCONF, переменная CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS будет добавлена в список, если она доступна. Если она недоступна, будет запрошена и добавлена переменная среды LIBRARY_PATH.

ALLOW_SYSTEM_INCLUDES

Сохраняет «системные» каталоги при преобразовании флагов каталогов включаемых файлов в CMAKE_PKG_CONFIG_CFLAGS и производных переменных.

Если этот параметр не задан, значение по умолчанию определяется первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES
2. Если переменная среды PKG_CONFIG_ALLOW_SYSTEM_CFLAGS определена, флаги сохраняются; в противном случае они фильтруются при преобразовании.

ALLOW_SYSTEM_LIBS

Сохраняет «системные» каталоги при преобразовании флагов каталогов библиотек в CMAKE_PKG_CONFIG_LIBS и производных переменных.

Если этот параметр не задан, значение по умолчанию определяется первым доступным из следующих значений:

1. CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS
2. Если переменная среды PKG_CONFIG_ALLOW_SYSTEM_LIBS определена, флаги сохраняются; в противном случае они фильтруются при преобразовании.

cmake_pkg_config(POPULATE <package> [<version>] [...])

Добавлено в версии 4.1.

Добавляет пакет в пространство имён целей pkg-config

cmake_pkg_config(POPULATE <package> [<version>]
                [REQUIRED] [EXACT] [QUIET]
                [PREFIX <prefix>]
                [BIND_PC_REQUIRES <<name>=<target>>...]
                [STRICTNESS <mode>]
                [ENV_MODE <mode>]
                [PC_LIBDIR <path>...]
                [PC_PATH <path>...]
                [DISABLE_UNINSTALLED <bool>]
                [PC_SYSROOT_DIR <path>]
                [TOP_BUILD_DIR <path>])

POPULATE позволяет вручную управлять разрешением списка Requires заданного пакета без импорта в нативную цель CMake. После добавления пакет и его зависимости будут использоваться для разрешения всех последующих команд POPULATE и IMPORT.

Для указания того, найден ли пакет, будет установлена переменная PKGCONFIG_<package>_FOUND.

cmake_pkg_config(IMPORT <package> [<version>] [...])

Добавлено в версии 4.1.

Импортирует цель pkg-config как цель CMake IMPORTED

cmake_pkg_config(IMPORT <package> [<version>]
                [REQUIRED] [EXACT] [QUIET]
                [NAME <name>]
                [PREFIX <prefix>]
                [BIND_PC_REQUIRES <<name>=<target>>...]
                [STRICTNESS <mode>]
                [ENV_MODE <mode>]
                [PC_LIBDIR <path>...]
                [PC_PATH <path>...]
                [DISABLE_UNINSTALLED <bool>]
                [PC_SYSROOT_DIR <path>]
                [TOP_BUILD_DIR <path>])

Создаёт нативную цель CMake IMPORTED, с которой можно связать другие цели с помощью target_link_libraries(). По умолчанию эта новая цель называется PkgConfig::<package>.

Для указания того, найден ли пакет, будет установлена переменная PKGCONFIG_<package>_FOUND.

NAME

Переопределяет имя создаваемой цели CMake, задавая PkgConfig::<name>. Это не влияет на переменную PKGCONFIG_<package>_FOUND.