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"]
          [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]
         )

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

Доступны следующие опции:

NAMES

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

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

HINTS, PATHS

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

PATH_SUFFIXES

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

DOC

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

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 или в сокращённой версии команды. Обычно это жёстко заданные предположения.

В macOS порядок предпочтения между компонентами пакетов в стиле Apple и UNIX определяется переменными CMAKE_FIND_FRAMEWORK и CMAKE_FIND_APPBUNDLE.

Переменная 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(), включён.