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

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

Примечание

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

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

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

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> в <PackageName>_ROOT переменной CMake и <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(), включён.