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"]
          [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]
         )

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

Доступные опции:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

REQUIRED

Остановите обработку с сообщением об ошибке, если ничего не найдено.

Если 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 или установив CMAKE_FIND_USE_PACKAGE_ROOT_PATH в FALSE. См. политику 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 или установив 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
Пути платформы, содержащиеся в этих переменных, обычно содержат местоположения установленного программного обеспечения. Например, /usr/local для систем на основе UNIX.
Поиск путей, указанных в опции 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.18/command/find_library.html