Spec-Zone.ru › CMake 3.27

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]... ]
          [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [VALIDATOR function]
          [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]
          [NO_CMAKE_INSTALL_PREFIX]
          [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 считывает пути из системной переменной среды.

Изменено в версии 3.24: На платформе Windows возможно включить запросы к реестру в качестве части каталогов, используя специальный синтаксис. Такие параметры будут проигнорированы на всех остальных платформах.

REGISTRY_VIEW

Новое в версии 3.24.

Укажите, какие представления реестра необходимо запросить. Этот параметр имеет смысл только на платформах Windows и будет проигнорирован на других. Если параметр не указан, используется представление TARGET, когда политика CMP0134 установлена в NEW. Обратитесь к CMP0134 для получения сведения о представлении по умолчанию, когда политика установлена в OLD.

64

Запрос 64-битного реестра. В 32-битной Windows всегда возвращает строку /REGISTRY-NOTFOUND.

32

Запрос 32-битного реестра.

64_32

Запрос обоих представлений (64 и 32) и создание пути для каждого.

32_64

Запрос обоих представлений (32 и 64) и создание пути для каждого.

HOST

Запрос реестра, соответствующего архитектуре хоста: 64 в 64-битной Windows и 32 в 32-битной Windows.

TARGET

Запрос реестра, соответствующего архитектуре, указанной переменной CMAKE_SIZEOF_VOID_P. Если не определена, используется представление HOST.

BOTH

Запрос обоих представлений (32 и 64). Порядок зависит от следующих правил: Если переменная CMAKE_SIZEOF_VOID_P определена, используется представление в зависимости от содержимого этой переменной:

  • 8: 64_32
  • 4: 32_64

Если переменная CMAKE_SIZEOF_VOID_P не определена, используется архитектура хоста:

  • 64-бит: 64_32
  • 32-бит: 32
PATH_SUFFIXES

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

VALIDATOR

Новое в версии 3.25.

Укажите function() для вызова для каждого найденного кандидата (нельзя указать macro(), это приведёт к ошибке). В функцию-валидатор будут переданы два аргумента: имя переменной результата и абсолютный путь к кандидату. Элемент будет принят, и поиск завершится, если функция не установит значение в переменной результата в вызывающей области в ложное значение. Переменная результата будет содержать истинное значение при входе в функцию-валидатор.

function(my_check validator_result_var item)
  if(NOT item MATCHES ...)
    set(${validator_result_var} FALSE PARENT_SCOPE)
  endif()
endfunction()

find_library (result NAMES ... VALIDATOR my_check)

Обратите внимание, что если используется кэшированный результат, поиск пропускается, и любые VALIDATOR игнорируются. Кэшированный результат не требуется для прохождения проверки функции.

DOC

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

NO_CACHE

Новое в версии 3.21.

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

Примечание

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

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

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

REQUIRED

Новое в версии 3.18.

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

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

  1. Если вызывается из модуля поиска или любого другого скрипта, загруженного с помощью вызова find_package(<PackageName>), выполняются уникальные префиксы поиска для текущего ищущегося пакета. См. политику CMP0074.

    Новое в версии 3.12.

    В частности, пути поиска, указанные следующими переменными, в порядке:

    1. <PackageName>_ROOT Переменная CMake, где <PackageName> — это имя пакета, сохраняющее регистр.

    2. <PACKAGENAME>_ROOT Переменная CMake, где <PACKAGENAME> — это имя пакета в верхнем регистре. См. политику CMP0144.

      Новое в версии 3.27.

    3. <PackageName>_ROOT Переменная среды, где <PackageName> — это имя пакета, сохраняющее регистр.

    4. <PACKAGENAME>_ROOT Переменная среды, где <PACKAGENAME> — это имя пакета в верхнем регистре. См. политику CMP0144.

      Новое в версии 3.27.

    Переменные корневой директории пакета сохраняются как стек, поэтому, если вызывается из вложенных модулей поиска или пакетов конфигурации, пути корней из родительского модуля поиска или пакета конфигурации будут искаться после путей из текущего модуля или пакета. Другими словами, порядок поиска будет <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, и т. д. Это можно пропустить, если передано NO_PACKAGE_ROOT_PATH или установив CMAKE_FIND_USE_PACKAGE_ROOT_PATH в FALSE.

    • <prefix>/lib/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлена, и <prefix>/lib для каждой <prefix> в <PackageName>_ROOT переменной CMake и <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, определённые в файлах платформы для текущей системы. Поиск CMAKE_INSTALL_PREFIX и CMAKE_STAGING_PREFIX можно пропустить, если передано NO_CMAKE_INSTALL_PREFIX или установив CMAKE_FIND_USE_INSTALL_PREFIX в FALSE. Все эти расположения можно пропустить, если передано 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 также могут привести к игнорированию некоторых из вышеуказанных расположений.

Новое в версии 3.16: Добавлены CMAKE_FIND_USE_<CATEGORY>_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(), включен.

© 2000–2024 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.27/command/find_library.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API