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]... ]
          [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]
          [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 считывает пути из переменной среды системы.

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, определённые в файлах платформы для текущей системы. Это можно пропустить, если передано 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 или в сокращённом варианте команды. Как правило, это жёстко закодированные предположения.

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