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_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, и поиск будет повторён в следующий раз, когда вызывается 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. Они предназначены для настройки пользовательской оболочки и, следовательно, используют системный разделитель путей (; в Windows и : в UNIX). Это можно пропустить, если передано 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> для подключения фреймворка к цели.

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