FindPackageHandleStandardArgs

Этот модуль предоставляет функции, предназначенные для использования в модулях поиска при реализации вызовов find_package(<PackageName>).

find_package_handle_standard_args

Эта команда обрабатывает REQUIRED, QUIET и аргументы, связанные с версиями, вызова find_package(). Она также устанавливает переменную <PackageName>_FOUND. Пакет считается найденным, если все перечисленные переменные содержат корректные результаты, например, корректные пути к файлам.

Существует две подписи:

find_package_handle_standard_args(<PackageName>
  (DEFAULT_MSG|<custom-failure-message>)
  <required-var>...
  )

find_package_handle_standard_args(<PackageName>
  [FOUND_VAR <result-var>]
  [REQUIRED_VARS <required-var>...]
  [VERSION_VAR <version-var>]
  [HANDLE_VERSION_RANGE]
  [HANDLE_COMPONENTS]
  [CONFIG_MODE]
  [NAME_MISMATCHED]
  [REASON_FAILURE_MESSAGE <reason-failure-message>]
  [FAIL_MESSAGE <custom-failure-message>]
  )

Переменная <PackageName>_FOUND будет установлена в значение TRUE, если все переменные <required-var>... являются корректными и все дополнительные ограничения удовлетворены, и в FALSE в противном случае. Сообщение об успехе или ошибке может быть выведено в зависимости от результатов и от того, были ли указаны опции REQUIRED и/или QUIET в вызове find_package().

Доступные опции:

(DEFAULT_MSG|<custom-failure-message>)

В простой подписи эта опция определяет сообщение об ошибке. Используйте DEFAULT_MSG для запроса вычисления стандартного сообщения (рекомендуется). Недействительно в полной подписи.

FOUND_VAR <result-var>

Устарело начиная с версии 3.3.

Указывает <PackageName>_FOUND или <PACKAGENAME>_FOUND в качестве переменной результата. Эта опция существует только для совместимости со старыми версиями CMake и теперь игнорируется. Переменные результата с обоими именами всегда устанавливаются для совместимости.

REQUIRED_VARS <required-var>...

Указывает переменные, необходимые для этого пакета. Их имена могут быть указаны в сгенерированном сообщении об ошибке, просящем пользователя задать значения отсутствующих переменных. Поэтому они обычно должны быть записями кэша, такими как FOO_LIBRARY, а не переменными вывода, такими как FOO_LIBRARIES.

Изменено в версии 3.18: Если HANDLE_COMPONENTS указано, эту опцию можно опустить.

VERSION_VAR <version-var>

Указывает имя переменной, содержащей версию найденного пакета. Эта версия будет проверена по отношению к (возможно) указанной требуемой версии, предоставленной вызовом find_package(), включая его опцию EXACT. Стандартные сообщения содержат информацию о требуемой версии и фактически найденной версии, независимо от того, соответствует ли версия или нет.

HANDLE_VERSION_RANGE

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

Включает обработку диапазона версий, если он указан. Без этой опции будет отображено предупреждение разработчику, если указан диапазон версий.

HANDLE_COMPONENTS

Включает обработку компонентов пакета. В этом случае команда сообщит, какие компоненты найдены, а какие отсутствуют, и переменная <PackageName>_FOUND будет установлена в значение FALSE, если любой из необходимых компонентов (т.е. не те, которые перечислены после опции OPTIONAL_COMPONENTS вызова find_package()) отсутствует.

CONFIG_MODE

Указывает, что вызывающий модуль поиска является оболочкой для вызова find_package(<PackageName> NO_MODULE). Это подразумевает значение VERSION_VAR равное <PackageName>_VERSION. Команда автоматически проверит, был ли найден файл конфигурации пакета.

REASON_FAILURE_MESSAGE <reason-failure-message>

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

Указывает пользовательское сообщение о причине ошибки, которое будет добавлено к стандартному сгенерированному сообщению.

FAIL_MESSAGE <custom-failure-message>

Указывает пользовательское сообщение об ошибке вместо использования стандартного сгенерированного сообщения. Не рекомендуется.

NAME_MISMATCHED

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

Указывает, что <PackageName> не соответствует ${CMAKE_FIND_PACKAGE_NAME}. Обычно это ошибка и вызывает предупреждение, но это может быть намеренным для использования команды для компонентов более крупного пакета.

Пример для простой подписи:

find_package_handle_standard_args(LibXml2 DEFAULT_MSG
  LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)

Пакет LibXml2 считается найденным, если LIBXML2_LIBRARY и LIBXML2_INCLUDE_DIR являются корректными. Тогда также устанавливается LibXml2_FOUND в значение TRUE. Если он не найден и был использован REQUIRED, происходит ошибка с message(FATAL_ERROR), независимо от того, использовался ли QUIET или нет. Если пакет найден, будет сообщено об успехе, включая содержимое первого <required-var>. При повторных запусках CMake это сообщение не будет выводиться снова.

Пример для полной подписи:

find_package_handle_standard_args(LibArchive
  REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
  VERSION_VAR LibArchive_VERSION)

В этом случае пакет LibArchive считается найденным, если LibArchive_LIBRARY и LibArchive_INCLUDE_DIR являются корректными. Также будет проверена версия LibArchive с использованием версии в LibArchive_VERSION. Так как FAIL_MESSAGE не указано, будут выведены стандартные сообщения.

Другой пример для полной подписи:

find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
find_package_handle_standard_args(Automoc4  CONFIG_MODE)

В этом случае модуль FindAutmoc4.cmake оборачивает вызов find_package(Automoc4 NO_MODULE) и добавляет дополнительный каталог поиска для automoc4. Затем вызов find_package_handle_standard_args генерирует соответствующее сообщение об успехе/ошибке.

find_package_check_version

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

Вспомогательная функция, которая может использоваться для проверки, является ли <version> допустимым по отношению к аргументам, связанным с версиями, в вызове find_package().

find_package_check_version(<version> <result-var>
  [HANDLE_VERSION_RANGE]
  [RESULT_MESSAGE_VARIABLE <message-var>]
  )

Переменная <result-var> будет содержать булево значение, отражающее результат проверки.

Доступные опции:

HANDLE_VERSION_RANGE

Включает обработку диапазона версий, если он указан. Без этой опции будет отображено предупреждение разработчику, если указан диапазон версий.

RESULT_MESSAGE_VARIABLE <message-var>

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

Пример использования:

find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
  RESULT_MESSAGE_VARIABLE reason)
if (result)
  message (STATUS "${reason}")
else()
  message (FATAL_ERROR "${reason}")
endif()