find_library

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

find_library (<VAR> name1 [path1 path2 ...])

Общая форма записи:

find_library (
          <VAR>
          name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [VALIDATOR function]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED]
          [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]
         )

Эта команда используется для поиска библиотеки. В кэше или обычной переменной, если указано NO_CACHE, с именем, указанным <VAR>, хранится результат этой команды. Если библиотека найдена, результат сохраняется в переменной, и поиск не будет повторён, если переменная не очищена. Если ничего не найдено, результат будет <VAR>-NOTFOUND.

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

NAMES

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

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

HINTS, PATHS

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

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

REGISTRY_VIEW

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

Укажите, какие представления реестра необходимо запросить. Этот параметр имеет смысл только на платформах Windows и будет проигнорирован на других. Если не указано, используется представление TARGET при CMP0134 политике CMP0134. Обратитесь к CMP0134 для определения стандартного представления, когда политика OLD.

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(), это приведёт к ошибке). Функции-валидатора будут переданы два аргумента: имя переменной результата и абсолютный путь к кандидату. Элемент будет принят, и поиск завершится, если функция установит значение в переменной результата в ложном значении в вызывающей области. Переменная результата будет содержать истинное значение при входе функции-валидатора.

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.

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

Примечание

Если переменная уже установлена до вызова (как обычная или переменная кэша), то поиск не произойдёт.

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

Этот параметр следует использовать с осторожностью, так как он может значительно увеличить стоимость повторных шагов конфигурации.

REQUIRED

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

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

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

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

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

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

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

   2. <PACKAGENAME>_ROOT Переменная CMake, где <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, определённых в файлах платформы для текущей системы. Поиск 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). Таким образом, можно указать имена файлов библиотек, такие как 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(), включен.