FindPkgConfig

Модуль pkg-config для CMake.

Находит исполняемый файл pkg-config и предоставляет команды для его использования в CMake:

find_package(PkgConfig [<version>] [QUIET] [REQUIRED] [...])

pkg-config — это программа командной строки для настройки сведений о зависимостях сборки. Первоначально разработанная FreeDesktop, она также доступна в нескольких реализациях, таких как pkgconf, u-config и аналогичные. Программа считывает данные пакетов из так называемых файлов метаданных PC (<module-name>.pc), которые могут устанавливаться вместе с пакетами. Этот модуль является оболочкой для исполняемого файла командной строки pkg-config.

Переменные результата

Этот модуль определяет следующие переменные:

PkgConfig_FOUND

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

Логическое значение, указывающее, найден ли исполняемый файл pkg-config (запрошенной версии).

PkgConfig_VERSION

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

Найденная версия pkg-config.

PKG_CONFIG_EXECUTABLE

Путь к программе pkg-config.

PKG_CONFIG_ARGN

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

Список аргументов, передаваемых pkg-config.

Модуль инициализирует PKG_CONFIG_EXECUTABLE и PKG_CONFIG_ARGN, но пользователь может переопределить их. О том, как инициализируются эти переменные, см. раздел Подсказки.

Команды

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

• pkg_check_modules()
• pkg_search_module()
• pkg_get_variable()

pkg_check_modules

Проверяет все указанные модули и задаёт различные переменные результата в вызывающей области видимости:

pkg_check_modules(
  <prefix>
  [QUIET]
  [REQUIRED]
  [NO_CMAKE_PATH]
  [NO_CMAKE_ENVIRONMENT_PATH]
  [IMPORTED_TARGET [GLOBAL]]
  <module-spec> [<module-spec>...]
)

Аргументы:

<prefix>

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

QUIET

Если указан этот аргумент, сообщения о состоянии не выводятся.

REQUIRED

Если указан этот аргумент, команда завершится с ошибкой, если не удастся найти какой-либо из указанных модулей.

NO_CMAKE_PATH, NO_CMAKE_ENVIRONMENT_PATH

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

Переменные кэша и среды CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH и CMAKE_APPBUNDLE_PATH будут добавлены в путь поиска pkg-config. Аргументы NO_CMAKE_PATH и NO_CMAKE_ENVIRONMENT_PATH отключают это поведение соответственно для переменных кэша и переменных среды. Если переменной PKG_CONFIG_USE_CMAKE_PREFIX_PATH присвоено значение FALSE, это поведение отключается глобально.

IMPORTED_TARGET [GLOBAL]

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

Этот аргумент создаёт импортированную цель с именем PkgConfig::<prefix>, которую можно передать непосредственно в качестве аргумента команде target_link_libraries(). Она объединит требования к использованию для всех указанных модулей <module-spec>....

GLOBAL

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

Этот аргумент используется вместе с IMPORTED_TARGET и делает импортированную цель доступной в глобальной области видимости.

Добавлено в версии 3.15: Параметры компоновщика, не являющиеся параметрами библиотек, которые сообщает pkg-config, сохраняются в свойстве цели INTERFACE_LINK_OPTIONS.

Изменено в версии 3.18: Каталоги включаемых файлов, указанные с помощью -isystem, сохраняются в свойстве цели INTERFACE_INCLUDE_DIRECTORIES. В предыдущих версиях CMake они сохранялись в свойстве INTERFACE_COMPILE_OPTIONS.

<module-spec>

Каждый <module-spec> может быть либо простым именем модуля (определяемым именем его файла метаданных PC <module-name>.pc), либо именем модуля с ограничением версии (поддерживаются операторы =, <, >, <= и >=). Ниже приведены примеры для модуля с именем foo с различными ограничениями:

• foo соответствует любой версии.
• foo<2 соответствует только версиям ниже 2.
• foo>=3.1 соответствует любой версии 3.1 или выше.
• foo=1.2.3 требует, чтобы версия foo была точно равна 1.2.3.

Переменные результата

При возврате могут быть заданы следующие переменные. Предусмотрено два набора значений: один для обычного случая (<XXX> = <prefix>), другой — для сведений, которые предоставляет pkg-config при вызове с параметром --static (<XXX> = <prefix>_STATIC).

<XXX>_FOUND

Логическая переменная, значение которой равно 1, если модуль или модули существуют.

<XXX>_LIBRARIES

Список только библиотек (без -l).

<XXX>_LINK_LIBRARIES

Библиотеки и их абсолютные пути.

<XXX>_LIBRARY_DIRS

Пути к библиотекам (без -L).

<XXX>_LDFLAGS

Все обязательные флаги компоновщика.

<XXX>_LDFLAGS_OTHER

Все остальные флаги компоновщика.

<XXX>_INCLUDE_DIRS

Флаги препроцессора -I (без -I).

<XXX>_CFLAGS

Все обязательные флаги cflags.

<XXX>_CFLAGS_OTHER

Остальные флаги компилятора.

Все переменные, кроме <XXX>_FOUND, могут содержать список, разделённый точками с запятой, если соответствующая переменная, возвращаемая pkg-config, содержит несколько значений.

Изменено в версии 3.18: Каталоги включаемых файлов, указанные с помощью -isystem, сохраняются в переменной <XXX>_INCLUDE_DIRS. В предыдущих версиях CMake они сохранялись в <XXX>_CFLAGS_OTHER.

Некоторые специальные переменные имеют префикс, зависящий от количества указанных <module-spec>. Если указан только один <module-spec>, <YYY> будет просто <prefix>, но если указано два или более элементов <module-spec>, <YYY> будет <prefix>_<module-name>.

<YYY>_VERSION

Версия модуля.

<YYY>_PREFIX

Каталог префикса модуля.

<YYY>_INCLUDEDIR

Каталог включаемых файлов модуля.

<YYY>_LIBDIR

Каталог библиотек модуля.

Изменено в версии 3.8: Для любого заданного <prefix> команду pkg_check_modules() можно вызывать несколько раз с разными параметрами. В предыдущих версиях CMake результаты кэшировались и возвращался первый успешный результат.

Изменено в версии 3.16: Если полный путь к найденной библиотеке определить не удаётся, но она всё ещё доступна компоновщику, передайте её как -l<name>. В предыдущих версиях CMake в этом случае возникала ошибка.

pkg_search_module

Ищет первое соответствие среди одной или нескольких заданных спецификаций модулей:

pkg_search_module(
  <prefix>
  [QUIET]
  [REQUIRED]
  [NO_CMAKE_PATH]
  [NO_CMAKE_ENVIRONMENT_PATH]
  [IMPORTED_TARGET [GLOBAL]]
  <module-spec> [<module-spec>...]
)

Поведение и аргументы этой команды совпадают с pkg_check_modules(), за исключением того, что вместо проверки всех указанных модулей она ищет только первое успешное соответствие.

Эту команду можно использовать, например, если известно, что у пакета могут быть разные <module-spec> для разных платформ или версий.

Переменные результата

Эта команда определяет те же переменные, что описаны выше, а также:

<prefix>_MODULE_NAME

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

Если модуль найден, переменная <prefix>_MODULE_NAME будет содержать имя соответствующего модуля. Эту переменную можно использовать, если команду pkg_get_variable() необходимо вызвать с аргументом <module-name>, найденным командой pkg_search_module().

pkg_get_variable

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

Получает значение переменной pkg-config и сохраняет его в переменной результата в вызывающей области видимости:

pkg_get_variable(
  <result-var>
  <module-name>
  <var-name>
  [DEFINE_VARIABLES <key>=<value>...]
)

Аргументы:

<result-var>

Имя переменной результата, в которой будет содержаться значение переменной pkg-config. Если pkg-config возвращает несколько значений для указанной переменной <var-name>, <result-var> будет содержать список, разделённый точками с запятой.

<module-name>

Имя модуля, определяемое именем его файла метаданных PC (<module-name>.pc).

<var-name>

Имя переменной pkg-config из файла метаданных PC <module-name>.pc.

DEFINE_VARIABLES <key>=<value>...

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

Укажите пары ключ-значение, чтобы переопределить переменные, влияющие на переменную, полученную с помощью pkg-config.

Подсказки

Перед вызовом find_package(PkgConfig) этот модуль принимает следующие переменные, влияющие на его поведение:

ENV{PKG_CONFIG_PATH}

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

ENV{PKG_CONFIG}

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

Переменная среды, которой можно присвоить путь к исполняемому файлу pkg-config. Она используется для инициализации переменной PKG_CONFIG_EXECUTABLE, если та ещё не задана.

PKG_CONFIG_EXECUTABLE

Этой переменной кэша можно присвоить путь к исполняемому файлу pkg-config. Модуль внутри себя вызывает find_program(), используя эту переменную.

PKG_CONFIG_ARGN

Этой переменной кэша можно присвоить список дополнительных аргументов, которые при необходимости передаются в pkg-config. Если она не задана, переменная инициализируется значением переменной среды PKG_CONFIG, если та задана. Первый аргумент этой переменной среды считается программой pkg-config, а все последующие аргументы используются для инициализации PKG_CONFIG_ARGN. Если такая переменная среды не определена, PKG_CONFIG_ARGN инициализируется пустой строкой. После сохранения переменной в кэше модуль её не обновляет.

PKG_CONFIG_USE_CMAKE_PREFIX_PATH

Определяет, должны ли команды pkg_check_modules() и pkg_search_module() добавлять пути из переменных кэша и среды CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH и CMAKE_APPBUNDLE_PATH в путь поиска pkg-config.

Если эта переменная не задана, поведение включено по умолчанию, если значение CMAKE_MINIMUM_REQUIRED_VERSION равно 3.1 или выше; в противном случае оно отключено.

Устаревшие переменные

Для обратной совместимости предоставляются следующие переменные:

PKG_CONFIG_FOUND

Устарела с версии 4.2: Используйте PkgConfig_FOUND, имеющую то же значение.

Логическое значение, указывающее, найден ли исполняемый файл pkg-config (запрошенной версии).

PKG_CONFIG_VERSION_STRING

Устарела с версии 4.2: Используйте PkgConfig_VERSION, имеющую то же значение.

Найденная версия pkg-config.

Примеры

Примеры: поиск pkg-config

Поиск pkg-config:

find_package(PkgConfig)

Поиск pkg-config с обязательным требованием его наличия (если он не найден, обработка прекращается с сообщением об ошибке):

find_package(PkgConfig REQUIRED)

Поиск pkg-config без вывода сообщений о состоянии, как это обычно делается в модулях поиска:

find_package(PkgConfig QUIET)

Примеры: использование pkg_check_modules()

Проверка наличия любой версии glib2. Если пакет найден, выходная переменная GLIB2_VERSION будет содержать фактически найденную версию:

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_check_modules(GLIB2 glib-2.0)
endif()

В следующем примере выполняется поиск glib2 версии 2.10 или выше. Если пакет найден, выходная переменная GLIB2_VERSION будет содержать фактически найденную версию:

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_check_modules(GLIB2 glib-2.0>=2.10)
endif()

В следующем примере выполняется поиск glib2-2.0 (версии 2.10 или выше) и gtk2+-2.0 любой версии. FOO будет считаться найденной только в том случае, если найдены оба модуля. Переменным FOO_glib-2.0_VERSION и FOO_gtk+-2.0_VERSION будут присвоены соответствующие найденные версии модулей.

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_check_modules(FOO glib-2.0>=2.10 gtk+-2.0)
endif()

В следующем примере требуется любая версия xrender:

find_package(PkgConfig QUIET REQUIRED)
pkg_check_modules(XRENDER REQUIRED xrender)

Выходные переменные, задаваемые при успешном вызове:

XRENDER_LIBRARIES=Xrender;X11
XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp

Пример: использование pkg_search_module()

Поиск пакета LibXml2, который может предоставляться с разными спецификациями модулей (libxml-2.0 или libxml2):

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_search_module(BAR libxml-2.0 libxml2 libxml>=2)
endif()

Пример: создание импортированной цели

В следующем примере на основе спецификаций модулей создаётся импортированная цель, которую можно использовать непосредственно в проекте без модуля поиска. Такие импортированные цели можно использовать, например, в случаях, когда известно, что пакет поддерживает pkg-config на всех поддерживаемых платформах:

find_package(PkgConfig QUIET REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14)
target_link_libraries(example PRIVATE PkgConfig::GTK)

Пример: использование pkg_get_variable()

Получение значения переменной girdir pkg-config из пакета Gobject:

find_package(PkgConfig QUIET)

if(PkgConfig_FOUND)
  pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
endif()

message(STATUS "${GI_GIRDIR}")

См. также

• Команда cmake_pkg_config() — современный и более функциональный способ работы с pkg-config в CMake без необходимости устанавливать исполняемый файл pkg-config.
• Модули поиска — сведения о написании модуля поиска.