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