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.16/command/find_library.html