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, загруженного с помощью find_package(<PackageName>), ищутся префиксы, уникальные для текущего ищущегося пакета. В частности, поиск в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT. Переменные корня пакета хранятся в стеке, поэтому если вызов происходит из вложенных модулей find, корневые пути родительского модуля find будут проверяться после путей текущего модуля, т.е. <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т.д. Это можно пропустить, если передать NO_PACKAGE_ROOT_PATH. См. политику CMP0074.
- <prefix>/lib/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix> в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT, если вызов происходит внутри модуля find, загруженного с помощью find_package(<PackageName>)
Проверяются пути, указанные в переменных кэша CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как списки, разделённые точкой с запятой. Это можно пропустить, если передать NO_CMAKE_PATH.
- <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.
- <prefix>/lib/<arch> если установлена CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix> в CMAKE_PREFIX_PATH
- CMAKE_LIBRARY_PATH
- CMAKE_FRAMEWORK_PATH
Проверяются пути, указанные параметром HINTS. Эти пути должны быть вычислены путём интроспекции системы, например, указанием местоположения другого найденного элемента. Заранее заданные предположения должны быть указаны с помощью параметра PATHS.
Проверяются стандартные системные переменные окружения. Это можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH является аргументом.
- Директории в LIB. В Windows: <prefix>/lib/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/lib для каждого <prefix>/[s]bin в PATH, и <entry>/lib для других записей в PATH, и директории в PATH сами по себе.
Проверка переменных CMake, определённых в файлах платформы для текущей системы. Это можно пропустить, если передать NO_CMAKE_SYSTEM_PATH.
- <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.14/command/find_library.html