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, <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(), включён.