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

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(), включён.