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

Если глобальная свойство FIND_LIBRARY_USE_LIB64_PATHS установлено, все пути поиска будут проверены в обычном режиме, со строкой 64/ добавленной в конец, и все совпадения с lib/ будут заменены на lib64/. Это свойство автоматически устанавливается для платформ, для которых это необходимо, если хотя бы один из языков, поддерживаемых командой project(), включён.