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