find_library

Краткая форма записи:

find_library (<VAR> <name> [<path>...])

Полная форма записи:

find_library (
          <VAR>
          {<name> | NAMES <name>... [NAMES_PER_DIR]}
          [HINTS {<path> | ENV <var>}...]
          [PATHS {<path> | ENV <var>}...]
          [REGISTRY_VIEW {64|32|64_32|32_64|HOST|TARGET|BOTH}]
          [PATH_SUFFIXES <suffix>...]
          [VALIDATOR <function>]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED|OPTIONAL]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [NO_CMAKE_INSTALL_PREFIX]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

Эта команда используется для поиска библиотеки.

Перед поиском find_library проверяет, определена ли переменная <VAR>. Если переменная не определена, выполняется поиск. Если переменная определена и ее значение равно NOTFOUND или заканчивается на -NOTFOUND, выполняется поиск. Если переменная содержит любое другое значение, поиск не выполняется.

Результаты поиска сохраняются в записи кэша с именем <VAR>. При последующих вызовах find_library с тем же значением <VAR> будет проверяться эта запись кэша. Такая оптимизация позволяет не повторять успешный поиск, пока запись кэша не будет unset().

Если библиотека найдена, в записи кэша <VAR> будет сохранено значение, полученное в результате поиска. Если ничего не найдено, будет сохранено значение <VAR>-NOTFOUND.

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

NAMES

Задает одно или несколько возможных имен библиотеки.

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

HINTS, PATHS

Задает каталоги для поиска в дополнение к расположениям по умолчанию. Подпараметр ENV var считывает пути из системной переменной среды.

Изменено в версии 3.24: На платформе Windows в список каталогов можно включать запросы к реестру, используя специальный синтаксис. Такие спецификации игнорируются на всех остальных платформах.

REGISTRY_VIEW

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

Задает представления реестра, к которым следует обращаться. Этот параметр имеет смысл только на платформах Windows и игнорируется на остальных. Если параметр не задан и политика CMP0134 установлена в значение NEW, используется представление TARGET. Сведения о представлении по умолчанию, используемом при политике OLD, см. в описании CMP0134.

64

Выполняет запрос к 64-разрядному реестру. В 32-разрядной Windows всегда возвращает строку /REGISTRY-NOTFOUND.

32

Выполняет запрос к 32-разрядному реестру.

64_32

Выполняет запрос к обоим представлениям (64 и 32) и формирует путь для каждого из них.

32_64

Выполняет запрос к обоим представлениям (32 и 64) и формирует путь для каждого из них.

HOST

Выполняет запрос к реестру, соответствующему архитектуре хоста: 64 в 64-разрядной Windows и 32 в 32-разрядной Windows.

TARGET

Выполняет запрос к реестру, соответствующему архитектуре, заданной переменной CMAKE_SIZEOF_VOID_P. Если она не определена, используется представление HOST.

BOTH

Выполняет запрос к обоим представлениям (32 и 64). Порядок определяется следующими правилами. Если переменная CMAKE_SIZEOF_VOID_P определена, используемое представление зависит от ее значения:

• 8: 64_32
• 4: 32_64

Если переменная CMAKE_SIZEOF_VOID_P не определена, учитывается архитектура хоста:

• 64-разрядная: 64_32
• 32-разрядная: 32

PATH_SUFFIXES

Задает дополнительные подкаталоги для проверки внутри каждого из рассматриваемых каталогов.

VALIDATOR

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

Задает function(), вызываемую для каждого найденного кандидата (задать macro() нельзя: это приведет к ошибке). Функции-валидатору передаются два аргумента: имя переменной результата и абсолютный путь к кандидату. Кандидат будет принят, и поиск завершится, если функция не установит значение переменной результата в false в вызывающей области видимости. При входе в функцию-валидатор переменная результата содержит значение true.

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_library (result NAMES ... VALIDATOR my_check)

Обратите внимание: если используется кэшированный результат, поиск пропускается, а все параметры VALIDATOR игнорируются. Кэшированный результат не обязан проходить проверку функции-валидатора.

DOC

Задает строку документации для записи кэша <VAR>.

NO_CACHE

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

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

Примечание

find_library по-прежнему проверяет <VAR>, как обычно: сначала переменную, затем запись кэша. Если хотя бы одна из них указывает на предыдущий успешный поиск, новый поиск не выполняется.

Предупреждение

Используйте этот параметр с осторожностью, поскольку он может значительно увеличить затраты на повторные этапы конфигурирования.

REQUIRED

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

Завершает обработку с сообщением об ошибке, если ничего не найдено; в противном случае поиск будет предпринят снова при следующем вызове find_library с той же переменной.

Добавлено в версии 4.1: Каждая команда find_library будет считаться командой REQUIRED, если включена переменная CMAKE_FIND_REQUIRED.

OPTIONAL

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

Игнорирует значение CMAKE_FIND_REQUIRED и продолжает работу без сообщения об ошибке, если ничего не найдено. Несовместим с REQUIRED.

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

1. Если команда вызвана из модуля поиска или любого другого скрипта, загруженного вызовом find_package(<PackageName>), выполняется поиск по префиксам, уникальным для текущего искомого пакета. См. политику CMP0074.

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

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

   1. Переменная CMake <PackageName>_ROOT, где <PackageName> — имя пакета с сохранением регистра.

   2. Переменная CMake <PACKAGENAME>_ROOT, где <PACKAGENAME> — имя пакета в верхнем регистре. См. политику CMP0144.

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

   3. Переменная среды <PackageName>_ROOT, где <PackageName> — имя пакета с сохранением регистра.

   4. Переменная среды <PACKAGENAME>_ROOT, где <PACKAGENAME> — имя пакета в верхнем регистре. См. политику CMP0144.

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

   Переменные корневых каталогов пакетов хранятся в виде стека, поэтому при вызове из вложенных модулей поиска или пакетов конфигурации пути из родительского модуля поиска или пакета конфигурации проверяются после путей из текущего модуля или пакета. Иными словами, порядок поиска будет таким: <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT} и т. д. Этот этап можно пропустить, передав NO_PACKAGE_ROOT_PATH или установив переменную CMAKE_FIND_USE_PACKAGE_ROOT_PATH в значение FALSE.

   • <prefix>/lib/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix> в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT, если вызов выполнен из модуля поиска, загруженного командой find_package(<PackageName>)

2. Пути, заданные в переменных кэша, относящихся к CMake. Они предназначены для использования в командной строке с параметром -DVAR=value. Значения интерпретируются как списки, разделенные точками с запятой. Этот этап можно пропустить, передав NO_CMAKE_PATH или установив переменную CMAKE_FIND_USE_CMAKE_PATH в значение FALSE.

   • <prefix>/lib/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_LIBRARY_PATH
   • CMAKE_FRAMEWORK_PATH

3. Пути, заданные в переменных среды, относящихся к CMake. Предполагается, что они задаются в конфигурации оболочки пользователя, поэтому для них используется собственный разделитель путей хоста (; в Windows и : в UNIX). Этот этап можно пропустить, передав NO_CMAKE_ENVIRONMENT_PATH или установив переменную CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH в значение FALSE.

   • <prefix>/lib/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_LIBRARY_PATH
   • CMAKE_FRAMEWORK_PATH
4. Поиск по путям, заданным параметром HINTS. Это должны быть пути, вычисленные путем анализа системы, например подсказка, основанная на расположении уже найденного объекта. Жестко заданные предположительные пути следует указывать с помощью параметра PATHS.

5. Поиск по стандартным системным переменным среды. Этот этап можно пропустить, передав NO_SYSTEM_ENVIRONMENT_PATH или установив переменную CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH в значение FALSE.

   • Каталоги в LIB и PATH.

   На хостах Windows в версиях CMake с 3.3 по 3.27 выполнялся поиск и по дополнительным путям: <prefix>/lib/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix>/[s]bin в PATH, а также <entry>/lib для остальных записей в PATH. Это поведение было удалено в CMake 3.28.

6. Поиск по переменным CMake, определенным в файлах Platform для текущей системы. Поиск по CMAKE_INSTALL_PREFIX и CMAKE_STAGING_PREFIX можно пропустить, передав NO_CMAKE_INSTALL_PREFIX или установив переменную CMAKE_FIND_USE_INSTALL_PREFIX в значение FALSE. Все эти расположения можно пропустить, передав NO_CMAKE_SYSTEM_PATH или установив переменную CMAKE_FIND_USE_CMAKE_SYSTEM_PATH в значение FALSE.

   • <prefix>/lib/<arch>, если задана переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
   • CMAKE_SYSTEM_LIBRARY_PATH
   • CMAKE_SYSTEM_FRAMEWORK_PATH

   Пути платформы, содержащиеся в этих переменных, указывают на расположения, где обычно устанавливается программное обеспечение. Например, /usr/local для платформ на основе UNIX.

7. Поиск по путям, заданным параметром PATHS или в краткой форме команды. Обычно это жестко заданные предположительные пути.

Переменные CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH и CMAKE_SYSTEM_IGNORE_PREFIX_PATH также могут приводить к игнорированию некоторых из перечисленных выше расположений.

В macOS переменные CMAKE_FIND_FRAMEWORK и CMAKE_FIND_APPBUNDLE определяют предпочтительный порядок поиска компонентов пакетов в стиле Apple и UNIX.

Переменная CMake CMAKE_FIND_ROOT_PATH задает один или несколько каталогов, добавляемых в начало всех остальных каталогов поиска. Фактически это переносит корень всего поиска в указанные расположения. Пути, являющиеся потомками CMAKE_STAGING_PREFIX, исключаются из этого переноса, поскольку эта переменная всегда задает путь в системе хоста. По умолчанию переменная CMAKE_FIND_ROOT_PATH пуста.

Переменную CMAKE_SYSROOT также можно использовать, чтобы указать ровно один каталог в качестве префикса. Установка CMAKE_SYSROOT имеет и другие последствия. Дополнительные сведения см. в документации по этой переменной.

Эти переменные особенно полезны при кросс-компиляции: с их помощью можно указать корневой каталог целевой среды, в котором CMake также будет выполнять поиск. По умолчанию сначала выполняется поиск в каталогах, перечисленных в CMAKE_FIND_ROOT_PATH, затем — в каталоге CMAKE_SYSROOT, а после этого — в каталогах без переноса корня. Поведение по умолчанию можно настроить с помощью CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. Это поведение можно переопределить для отдельного вызова с помощью параметров:

CMAKE_FIND_ROOT_PATH_BOTH

Выполняет поиск в описанном выше порядке.

NO_CMAKE_FIND_ROOT_PATH

Не использует переменную CMAKE_FIND_ROOT_PATH.

ONLY_CMAKE_FIND_ROOT_PATH

Выполняет поиск только в каталогах с перенесенным корнем и каталогах внутри CMAKE_STAGING_PREFIX.

Порядок поиска по умолчанию устроен так, чтобы в наиболее распространенных случаях начинать с наиболее специфичных расположений и переходить к наименее специфичным. Проекты могут изменить порядок, просто вызвав команду несколько раз и используя параметры NO_*:

find_library (<VAR> NAMES name PATHS <paths>... NO_DEFAULT_PATH)
find_library (<VAR> NAMES name)

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

Если параметру NAMES передано несколько значений, по умолчанию команда рассматривает по одному имени за раз и ищет его во всех каталогах. Параметр NAMES_PER_DIR указывает команде рассматривать по одному каталогу за раз и искать в нем все имена.

Каждое имя библиотеки, указанное параметру NAMES, сначала рассматривается как есть, если оно содержит суффикс библиотеки, а затем — с платформенными префиксами (например, lib) и суффиксами (например, .so), задаваемыми переменными CMAKE_FIND_LIBRARY_PREFIXES и CMAKE_FIND_LIBRARY_SUFFIXES. Поэтому можно указывать напрямую такие имена файлов библиотек, как libfoo.a. Это можно использовать для поиска статических библиотек в UNIX-подобных системах.

Если найденная библиотека является фреймворком, переменной <VAR> будет присвоен полный путь к фреймворку <fullPath>/A.framework. Если в качестве библиотеки используется полный путь к фреймворку, CMake применит -framework A и -F<fullPath> для связывания фреймворка с целью.

Если задана переменная CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX, все пути поиска проверяются как обычно, с добавленным суффиксом, а также с заменой всех вхождений lib/ на lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/. Эта переменная переопределяет глобальные свойства FIND_LIBRARY_USE_LIB32_PATHS, FIND_LIBRARY_USE_LIBX32_PATHS и FIND_LIBRARY_USE_LIB64_PATHS.

Если установлено глобальное свойство FIND_LIBRARY_USE_LIB32_PATHS, все пути поиска проверяются как обычно, с добавленным 32/, а все вхождения lib/ заменяются на lib32/. Это свойство автоматически устанавливается для платформ, которым оно необходимо, если включен хотя бы один из языков, поддерживаемых командой project().

Если установлено глобальное свойство FIND_LIBRARY_USE_LIBX32_PATHS, все пути поиска проверяются как обычно, с добавленным x32/, а все вхождения lib/ заменяются на libx32/. Это свойство автоматически устанавливается для платформ, которым оно необходимо, если включен хотя бы один из языков, поддерживаемых командой project().

Если установлено глобальное свойство FIND_LIBRARY_USE_LIB64_PATHS, все пути поиска проверяются как обычно, с добавленным 64/, а все вхождения lib/ заменяются на lib64/. Это свойство автоматически устанавливается для платформ, которым оно необходимо, если включен хотя бы один из языков, поддерживаемых командой project().