find_library

Короткая форма записи:

find_library (<VAR> name1 [path1 path2 ...])

Общая форма записи:

find_library (
          <VAR>
          name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED]
          [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]
         )

Эта команда используется для поиска библиотеки. Запись кэша или обычная переменная, если указано NO_CACHE, с именем <VAR> создаётся для хранения результата этой команды. Если библиотека найдена, результат сохраняется в переменной, и поиск не будет повторён, если переменная не очищена. Если ничего не найдено, результат будет <VAR>-NOTFOUND.

Доступные параметры:

NAMES

Укажите одно или несколько возможных имён для библиотеки.

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

HINTS, PATHS

Укажите каталоги для поиска помимо стандартных расположений. Параметр ENV var считывает пути из системной переменной окружения.

PATH_SUFFIXES

Укажите дополнительные подкаталоги для проверки ниже каждого каталога, который в противном случае рассматривается.

DOC

Укажите строку документации для записи кэша <VAR>.

NO_CACHE

Новая функция в версии 3.21.

Результат поиска будет сохранён в обычной переменной, а не в записи кэша.

Примечание

Если переменная уже задана перед вызовом (как обычная или переменная кэша), то поиск не выполнится.

Предупреждение

Этот параметр следует использовать с осторожностью, так как он может значительно увеличить стоимость повторных шагов конфигурации.

REQUIRED

Новая функция в версии 3.18.

Прекратите обработку с сообщением об ошибке, если ничего не найдено, в противном случае поиск будет предпринят снова в следующий раз, когда find_library будет вызван с той же переменной.

Если NO_DEFAULT_PATH указано, то дополнительные пути к поиску не добавляются. Если NO_DEFAULT_PATH не указано, процесс поиска выполняется следующим образом:

1. Новая функция в версии 3.12: Если вызывается из модуля поиска или любого другого сценария, загруженного при вызове find_package(<PackageName>), поиск префиксов, уникальных для текущего искомого пакета. В частности, ищем в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT. Переменные корневых папок пакетов поддерживаются как стек, поэтому, если вызываются вложенные модули поиска или пакеты конфигурации, корневые пути родительского модуля поиска или пакета конфигурации будут просматриваться после путей текущего модуля или пакета. Другими словами, порядок поиска будет <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т.д. Это можно пропустить, если передать NO_PACKAGE_ROOT_PATH или установив CMAKE_FIND_USE_PACKAGE_ROOT_PATH в FALSE. См. политику 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 или установив CMAKE_FIND_USE_CMAKE_PATH в FALSE.

   • <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 или установив CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH в FALSE.

   • <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 или установив CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH в FALSE.

   • Каталоги в LIB и PATH.
   • На системах Windows: <prefix>/lib/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/lib для каждого <prefix>/[s]bin в PATH, и <entry>/lib для других записей в PATH.

6. Проверка переменных CMake, определённых в файлах платформы для текущей системы. Это можно пропустить, передав NO_CMAKE_SYSTEM_PATH или установив CMAKE_FIND_USE_CMAKE_SYSTEM_PATH в FALSE.

   • <prefix>/lib/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/lib для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
   • CMAKE_SYSTEM_LIBRARY_PATH
   • CMAKE_SYSTEM_FRAMEWORK_PATH

   Пути в этих переменных платформы — это места, которые обычно включают установленное программное обеспечение. Пример — /usr/local для систем на основе UNIX.

7. Проверка путей, заданных параметром PATHS или в сокращённой форме команды. Это обычно зашифрованные предположения.

Переменные CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH и CMAKE_SYSTEM_IGNORE_PREFIX_PATH также могут привести к игнорированию некоторых из указанных выше расположений.

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