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 ...]]
          [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

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

DOC

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

NO_CACHE

Новое в версии 3.21.

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

Примечание

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

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

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

REQUIRED

Новое в версии 3.18.

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

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

1. Новое в версии 3.12: Если вызывается из модуля поиска или любого другого скрипта, загруженного при вызове find_package(<PackageName>), поиск префиксов, уникальных для текущего искомого пакета. В частности, поиск в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT. Переменные корня пакета поддерживаются как стек, поэтому при вызове из вложенных модулей поиска или конфигурационных пакетов корневые пути родительского модуля поиска или конфигурационного пакета будут проверяться после путей текущего модуля или пакета. Другими словами, порядок поиска будет <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т.д. Это можно пропустить, если передано NO_PACKAGE_ROOT_PATH или установив CMAKE_FIND_USE_PACKAGE_ROOT_PATH в значение FALSE. См. политику CMP0074.

   • <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 хостах: <prefix>/lib/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix>/[s]bin в PATH, и <entry>/lib для других записей в PATH.

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