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_LIB32_PATHS установлено, все пути поиска будут проверяться как обычно, с добавленным 32/, и все совпадения lib/ будут заменены на lib32/. Это свойство автоматически устанавливается для платформ, которым это требуется, если хотя бы один из языков, поддерживаемых командой project(), включён.

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