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

1. Если вызов происходит внутри модуля поиска, загруженного 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>)
2. Искать пути, указанные в переменных кэша, специфичных для CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как ;-списки. Это можно пропустить, если передано NO_CMAKE_PATH.
   • <prefix>/lib/<arch> если установлено CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix> в CMAKE_PREFIX_PATH
   • CMAKE_LIBRARY_PATH
   • CMAKE_FRAMEWORK_PATH
3. Искать пути, указанные в переменных среды, специфичных для 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
4. Искать пути, указанные в опции HINTS . Они должны быть путями, вычисленными системой, такими как подсказка, предоставленная местоположением другого найденного элемента. Жестко закодированные предположения должны быть указаны с помощью опции PATHS.
5. Искать стандартные системные переменные среды. Это можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH является аргументом.
   • Директории в LIB. На хостах Windows: <prefix>/lib/<arch> если установлено CMAKE_LIBRARY_ARCHITECTURE, и <prefix>/lib для каждого <prefix>/[s]bin в PATH, и <entry>/lib для других записей в PATH, и директории в PATH сами по себе.
6. Искать переменные 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
7. Искать пути, указанные в опции 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)

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

Когда для параметра 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(), включён.