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. См. политику CMP0074.
- <prefix>/lib/<arch> если установлена переменная CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждой <prefix> в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT, если вызов происходит из модуля поиска, загруженного с помощью 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.15/command/find_library.html