find_library

Сокращенная запись:

find_library (<VAR> name1 [path1 path2 ...])

Общая запись:

find_library (
          <VAR>
          name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
          [HINTS path1 [path2 ... ENV var]]
          [PATHS path1 [path2 ... ENV var]]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [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]
         )

Эта команда используется для поиска библиотеки. В кэше создается запись с именем <VAR>, чтобы сохранить результат этой команды. Если библиотека найдена, результат сохраняется в переменной, и поиск не повторяется, пока переменная не будет очищена. Если ничего не найдено, результат будет <VAR>-NOTFOUND, и поиск будет повторен в следующий раз, когда find_library вызывается с той же переменной.

Доступны следующие параметры:

NAMES

Укажите одно или несколько возможных имен библиотеки.

При указании имен с и без суффикса версии рекомендуется сначала указывать имя без версии, чтобы локально собранные пакеты находились перед пакетами, предоставленными дистрибутивами.

HINTS, PATHS

Укажите каталоги для поиска помимо стандартных. Параметр ENV var считывает пути из переменной среды системы.

PATH_SUFFIXES

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

DOC

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

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

Если вызов происходит внутри модуля поиска или любом другом скрипте, загруженном с помощью вызова 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>)
Искать пути, указанные в переменных кэша 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
Искать пути, указанные в переменных среды 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
Искать пути, указанные параметром HINTS. Эти пути должны быть вычислены путём осмотра системы, например, указанием местоположения другого найденного элемента. Заранее заданные предположения должны быть указаны с помощью параметра PATHS.
Искать стандартные системные переменные среды. Это можно пропустить, передав NO_SYSTEM_ENVIRONMENT_PATH или установив CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH в FALSE.
- Каталоги в PATH и INCLUDE.
- В Windows: <prefix>/lib/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/lib для каждого <prefix>/[s]bin в PATH, и <entry>/lib для других записей в PATH.
Искать переменные 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
Искать пути, указанные параметром 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(), включён.

© 2000–2020 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.17/command/find_library.html