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_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 не указана, процесс поиска выполняется следующим образом:

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

В OS X переменные 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–2019 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.10/command/find_library.html