Spec-Zone.ru › CMake

find_path

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

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

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

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [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(), это приведёт к ошибке). В функцию-валидатор будут переданы два аргумента: имя переменной результата и абсолютный путь к кандидату. Элемент будет принят и поиск завершится, если функция не установит значение в переменной результата false в области вызова. Переменная результата будет содержать true значение при входе в функцию-валидатор.

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

find_path (result NAMES ... VALIDATOR my_check)

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

DOC

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

NO_CACHE

Добавлена в версии 3.21.

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

Примечание

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

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

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

REQUIRED

Добавлена в версии 3.18.

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

Если 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>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/include для каждого <prefix> в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT, если вызов произошёл внутри модуля поиска, загруженного find_package(<PackageName>)

  2. Пути поиска, указанные в переменных кэша, специфичных для CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как списки, разделённые точкой с запятой. Это можно пропустить, если NO_CMAKE_PATH передано или установив CMAKE_FIND_USE_CMAKE_PATH в FALSE.

    • <prefix>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
    • CMAKE_INCLUDE_PATH
    • CMAKE_FRAMEWORK_PATH

  3. Пути поиска, указанные в переменных среды, специфичных для CMake. Они предназначены для установки в конфигурации оболочки пользователя и поэтому используют разделитель путей по умолчанию для платформы (; в Windows и : в UNIX). Это можно пропустить, если NO_CMAKE_ENVIRONMENT_PATH передано или установив CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH в FALSE.

    • <prefix>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/include для каждого <prefix> в CMAKE_PREFIX_PATH
    • CMAKE_INCLUDE_PATH
    • CMAKE_FRAMEWORK_PATH
  4. Проверяются пути, указанные опцией HINTS. Это пути, вычисленные посредством анализа системы, например, подсказка, полученная от местоположения уже найденного элемента. Запрограммированные догадки должны указываться с помощью опции PATHS.

  5. Проверяются стандартные переменные среды системы. Это можно пропустить, если NO_SYSTEM_ENVIRONMENT_PATH передано или установив CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH в FALSE.

    • Каталоги в INCLUDE и PATH.

    В системах Windows в CMake 3.3 по 3.27 проверялись дополнительные пути: <prefix>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/include для каждого <prefix>/[s]bin в PATH, и <entry>/include для других записей в PATH. Это поведение было удалено в CMake 3.28.

  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>/include/<arch> если CMAKE_LIBRARY_ARCHITECTURE установлено, и <prefix>/include для каждого <prefix> в CMAKE_SYSTEM_PREFIX_PATH
    • CMAKE_SYSTEM_INCLUDE_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_INCLUDE. Это поведение можно переопределить вручную для каждого вызова с помощью опций:

CMAKE_FIND_ROOT_PATH_BOTH

Поиск в порядке, описанном выше.

NO_CMAKE_FIND_ROOT_PATH

Не использовать переменную CMAKE_FIND_ROOT_PATH.

ONLY_CMAKE_FIND_ROOT_PATH

Искать только в переустановленных каталогах и каталогах ниже CMAKE_STAGING_PREFIX.

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

find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_path (<VAR> NAMES name)

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

При поиске фреймворков, если файл указан как A/b.h, то поиск фреймворка будет искать A.framework/Headers/b.h. Если это найдено, путь будет установлен на путь к фреймворку. CMake преобразует это в правильную опцию -F для включения файла.

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

Spec-Zone.ru

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